Skip to content

Commit

Permalink
docs: Add info to maintaining doc about deprecations
Browse files Browse the repository at this point in the history
  • Loading branch information
manuel.carrera committed Sep 18, 2023
1 parent 9e23a83 commit e594383
Showing 1 changed file with 28 additions and 3 deletions.
31 changes: 28 additions & 3 deletions modules/docs/mdx/MAINTAINING.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ Kit!
- [Forward Merge Workflow](#forward-merge-workflow)
- [Release Minor Workflow](#release-minor-workflow)
- [Release Workflow](#release-workflow)
- [Deprecations](#deprecations)
- [How To Deprecate](#how-to-deprecate)
- [Releases](#releases)
- [Patch Releases](#patch-releases)
- [Minor Releases](#minor-releases)
Expand Down Expand Up @@ -123,6 +125,28 @@ are initiated automatically when a commit is merged to `prerelease/minor` or `pr
a more in-depth review of the workflow,
[view the source code](https://github.com/Workday/canvas-kit/blob/master/.github/workflows/release-minor.yml).

## Deprecations

We add the [@deprecated](https://jsdoc.app/tags-deprecated.html) from JSDoc to code that we plan to
remove in the near future. Al though you can still consume this code, we want consumers to move to a
utility or component that is more stable.

### How To Deprecate

When deprecating a component or utility use the following pattern:

```tsx
/**
* ### ⚠️ ${ComponentName/Utility} has been deprecated. Optionally give a reason as to why. ⚠️
* - Please consider using [`${OtherComponent/Utility}`](insert link to documentation) in ${packageName}.
* @deprecated
*/
```

Attach this block of JSDoc directly above to all exported members that relate to the deprecation.

Be sure to add any additional information to an upgrade guide if necessary.

## Releases

### Patch Releases
Expand Down Expand Up @@ -270,12 +294,13 @@ last release tag. So for example, a V8 canary would look something like this:
## Codemods

We use codemods to reduce friction for consumers as they make changes and do upgrades. Codemods are
accompany major version releases since v5, and can also be released in minor releases if users want to apply some changes sooner.
accompany major version releases since v5, and can also be released in minor releases if users want
to apply some changes sooner.

### Add a New Codemod

Adding a new codemod is pretty straightforward, but this guide will make sure you don't miss any steps
along the way.
Adding a new codemod is pretty straightforward, but this guide will make sure you don't miss any
steps along the way.

First, you need to add a new command to the root CLI. For this example, we'll pretend you're adding
a new v10 codemod.
Expand Down

0 comments on commit e594383

Please sign in to comment.