|
| 1 | +# Deployment and versioning |
1 | 2 |
|
2 | | -Please find all the documentation about contributions in the directory `packages/contributing`. |
3 | | -You can start with the Getting Started in `packages/contributing/contributing-getting-started.mdx`. |
| 3 | +**NB:** releases process is handled by ODS core team but you can still have a look here about our process. |
| 4 | + |
| 5 | +<!-- TOC --> |
| 6 | + |
| 7 | +* [Deployment and versioning](#deployment-and-versioning) |
| 8 | +* [Deployment](#deployment) |
| 9 | +* [Releases](#releases) |
| 10 | +* [Versioning commands: what level of tag to use?](#versioning-commands--what-level-of-tag-to-use) |
| 11 | +* [Patch: fix a bug](#patch--fix-a-bug) |
| 12 | +* [Minor: add extra features](#minor--add-extra-features) |
| 13 | +* [Major: breaking changes](#major--breaking-changes) |
| 14 | +* [PRE-patch: prepare a future patch release](#pre-patch--prepare-a-future-patch-release) |
| 15 | +* [PRE-minor: prepare a future release without breaking changes](#pre-minor--prepare-a-future-release-without-breaking-changes) |
| 16 | +* [PRE-major: prepare a future release with breaking changes](#pre-major--prepare-a-future-release-with-breaking-changes) |
| 17 | +* [PRE-release: prepare a new pre-release](#pre-release--prepare-a-new-pre-release) |
| 18 | +* [Graduate a release](#graduate-a-release) |
| 19 | + |
| 20 | +<!-- TOC --> |
| 21 | + |
| 22 | +## Deployment |
| 23 | + |
| 24 | +release/next acts as our main branch, then for major and minor versioning a new release/* branch is created. |
| 25 | + |
| 26 | +For patch versioning, it can be added in the specific release/* or release/next, depending on its scope. |
| 27 | + |
| 28 | +## Releases |
| 29 | + |
| 30 | +In order to make a new release of the `ODS` packages, you must: |
| 31 | + |
| 32 | +- be sure that you are on a release branch like `release/next` or `release/X.Y` |
| 33 | +- no local changes to commit |
| 34 | +- your local branch is up-to-date |
| 35 | +- add a migration guide when there are breaking changes |
| 36 | + |
| 37 | +Then, to make a release, you have to execute the npm script `yarn ods:<VERSION_TYPE>` |
| 38 | +where `<VERSION_TYPE>` can be `patch`, `minor`, `major`, `premajor` `prerelase` or `graduate`. |
| 39 | + |
| 40 | +### Versioning commands: what level of tag to use? |
| 41 | + |
| 42 | +Here's a summed up table of which command to launch to create the appropriate tag: |
| 43 | + |
| 44 | +| Command | Target | Usage | version before | version after | |
| 45 | +|-----------------------|--------------|--------------------------------------|------------------|-----------------| |
| 46 | +| `yarn ods:prepatch` | `testing` | Prepare patch release | `1.0.0` | `1.0.1-alpha.0` | |
| 47 | +| `yarn ods:preminor` | `testing` | Prepare minor release | `1.0.0` | `1.1.0-alpha.0` | |
| 48 | +| `yarn ods:premajor` | `testing` | Prepare major release | `1.0.0` | `2.0.0-alpha.0` | |
| 49 | +| `yarn ods:prerelease` | `testing` | Prepare a new pre-release | `1.2.3-alpha.2` | `1.2.3-alpha.3` | |
| 50 | +| `yarn ods:patch` | `production` | Fix a bug | `1.0.0` | `1.0.1` | |
| 51 | +| `yarn ods:minor` | `production` | Add features without breaking change | `1.0.0` | `1.1.0` | |
| 52 | +| `yarn ods:major` | `production` | Add breaking change | `1.0.0` | `2.0.0` | |
| 53 | +| `yarn ods:graduate` | `production` | From `-alpha` versions to plain tag | `3.1.2-alpha.21` | `3.1.2` | |
| 54 | + |
| 55 | +You can find all explanations for these commands below: |
| 56 | + |
| 57 | +### Patch: fix a bug |
| 58 | + |
| 59 | +You fixed a bug **(without any other breaking changes)** for a released version in the branch `release/X.Y`. |
| 60 | +You have to release it from the same branch: |
| 61 | + |
| 62 | +```bash |
| 63 | +yarn ods:patch |
| 64 | +``` |
| 65 | + |
| 66 | +### Minor: add extra features |
| 67 | + |
| 68 | +You added one or several features **without any breaking changes** in the branch `release/next`. |
| 69 | +Create a release branch from up-to-date `release/next` that corresponds to the version you are going to release like `release/X.Y`. |
| 70 | + |
| 71 | +Then, you have to generate a minor version from your branch. |
| 72 | + |
| 73 | +```bash |
| 74 | +yarn ods:minor |
| 75 | +``` |
| 76 | + |
| 77 | +The release branch will be used for bugfixes later (patch). |
| 78 | +It will be used for bug fixes later (patch). |
| 79 | +Once the support for the version has ended, the branch will be un-referenced. |
| 80 | + |
| 81 | +### Major: breaking changes |
| 82 | + |
| 83 | +You added breaking changes in the `release/next` branch: |
| 84 | + |
| 85 | +Create a release branch from up-to-date `release/next` that corresponds to the version you are going to release like `release/X.Y`. |
| 86 | +In `docs/migration`, rename the migration guide previously created according to the version like `MIGRATION-x.y-to-next.mdx` to `MIGRATION-x.y-to-z.y.mdx`. |
| 87 | +Create a new empty migration guide for future release: `MIGRATION-x.y-to-next.mdx`. |
| 88 | + |
| 89 | +Then, in `packages/tools/storybook/stories/code/migration`, create a stories for the version you are going to release. |
| 90 | +And add the following imports and Meta title: |
| 91 | +```typescript |
| 92 | +import { Meta, Description } from '@storybook/addon-docs'; |
| 93 | +import MigrationXxToYx from '../../../../../../packages/doc/src/migration/MIGRATION-X.x-to-Y.x.mdx'; |
| 94 | + |
| 95 | +<Meta title="Code/Migration guide/X.x to Y.x" /> |
| 96 | + |
| 97 | +<MigrationXxToYx /> |
| 98 | +``` |
| 99 | + |
| 100 | +Then, you have to generate a major version from your branch. |
| 101 | + |
| 102 | +```bash |
| 103 | +yarn ods:major |
| 104 | +``` |
| 105 | + |
| 106 | +The release branch will be used for bugfixes later (patch). |
| 107 | +Once the support for the version has ended, the branch will be unreferenced. |
| 108 | + |
| 109 | +### PRE-patch: prepare a future patch release |
| 110 | + |
| 111 | +You fixed a bug in the `release/next` branch, and you want to release it as a candidate for testing purpose only **(not |
| 112 | +production)**. |
| 113 | + |
| 114 | +You can generate a PRE-patch version from `release/next` branch: |
| 115 | + |
| 116 | +```bash |
| 117 | +yarn ods:prepatch |
| 118 | +``` |
| 119 | + |
| 120 | +Once this version is finalized, you will have to graduate the release: see graduate release below. |
| 121 | + |
| 122 | +### PRE-minor: prepare a future release without breaking changes |
| 123 | + |
| 124 | +You added features in the `release/next` branch, and you want to release it as a candidate for testing purpose only **( |
| 125 | +not production)**. |
| 126 | + |
| 127 | +You can generate a PRE-minor version from `release/next` branch: |
| 128 | + |
| 129 | +```bash |
| 130 | +yarn ods:preminor |
| 131 | +``` |
| 132 | + |
| 133 | +Once this version is finalized, you will have to graduate the release: see Graduate a release below. |
| 134 | + |
| 135 | +### PRE-major: prepare a future release with breaking changes |
| 136 | + |
| 137 | +You added features in the `release/next` branch, and you want to release it as a candidate for testing purpose only **( |
| 138 | +not production)**. |
| 139 | + |
| 140 | +You can generate a PRE-major version from `release/next` branch: |
| 141 | + |
| 142 | +```bash |
| 143 | +yarn ods:premajor |
| 144 | +``` |
| 145 | + |
| 146 | +Then create a release branch from the commit tag that correspond to the version like `release/X.Y-alpha`. |
| 147 | +It will be used later in case of modification (fix, features, breaking changes). |
| 148 | +Once this version is finalized, you will have to graduate the release: see Graduate a release below. |
| 149 | + |
| 150 | +### PRE-release: prepare a new pre-release |
| 151 | + |
| 152 | +You already are in a prerelease version with `alpha.x` (meaning you previously made a `pre-major`, `pre-minor` |
| 153 | +or `pre-patch`). |
| 154 | + |
| 155 | +You want to prerelease a new one and increment the `alpha` number. You want to continue prerelease for testing purpose |
| 156 | +only **(not production)**. |
| 157 | + |
| 158 | +You have to generate a new PRE-release version from `release/X.Y-alpha` branch: |
| 159 | + |
| 160 | +```bash |
| 161 | +yarn ods:prerelease |
| 162 | +``` |
| 163 | + |
| 164 | +Once this version is finalized, you will have to graduate the release: see Graduate a release below. |
| 165 | + |
| 166 | +### Graduate a release |
| 167 | + |
| 168 | +You already released a `pre-major/minor/patch` or a `pre-release`. |
| 169 | + |
| 170 | +All tests are valid, you want to release the final version like from `1.2.0-alpha-X` to `1.2.0`. |
| 171 | + |
| 172 | +You have to graduate the version from `release/X.Y-alpha` branch: |
| 173 | + |
| 174 | +```bash |
| 175 | +yarn ods:graduate |
| 176 | +``` |
| 177 | + |
| 178 | +Then, create a release branch from the commit tag that correspond to the version like `release/X.Y`. |
| 179 | +It will be used for bug fixes later (patch). |
| 180 | +Once the support for the version has ended, the branch will be un-referenced. |
0 commit comments