You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: DEVELOPMENT.md
+75-47Lines changed: 75 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,65 +2,83 @@
2
2
3
3
## Releases
4
4
5
-
New releases should be created from release branches originating from the `dev` branch. When you are ready to begin the release process:
6
-
7
-
- Make sure you've pulled all the changes from GitHub for both `dev` and `main` branches.
8
-
- Check out the `dev` branch.
9
-
- Create a new `release-next` branch (eg, `git checkout -b release-next`).
10
-
- Technically, any `release-*next*` branch name will work as this is what triggers our GitHub CI workflow that will ultimately publish the release - but we just always use `release-next`
11
-
- Merge `main` into the release branch.
5
+
New 7.x releases should be created from release branches originating from the `dev` branch. If you are doing a 6.x release, please see the [v6 section](#v6-releases) below.
6
+
7
+
When you are ready to begin the release process:
8
+
9
+
- Make sure you've pulled all the changes from GitHub for both `dev` and `main` branches
10
+
-`git checkout main && git pull origin main`
11
+
-`git checkout dev && git pull origin dev`
12
+
- Check out the `dev` branch
13
+
-`git checkout dev`
14
+
- Create a new `release-next` branch
15
+
-`git checkout -b release-next`
16
+
- Technically, any `release-*` branch name will work as this is what triggers our GitHub CI workflow that will ultimately publish the release - but we just always use `release-next`
17
+
- We are using `release-v6` for [ongoing v6 releases](#v6-releases)
18
+
- Merge `main` into the `release-next` branch
19
+
-`git merge --no-ff main`
12
20
13
21
Changesets will do most of the heavy lifting for our releases. When changes are made to the codebase, an accompanying changeset file should be included to document the change. Those files will dictate how Changesets will version our packages and what shows up in the changelogs.
14
22
15
23
### Starting a new pre-release
16
24
17
-
- Ensure you are on the new `release-next` branch.
18
-
- Enter Changesets pre-release mode using the `pre` tag: `pnpm changeset pre enter pre`.
19
-
- Commit the change and push the `release-next` branch to GitHub.
20
-
- Wait for the release workflow to finish. The Changesets action in the workflow will open a PR that will increment all versions and generate the changelogs.
21
-
- Check out the PR branch created by changesets locally
22
-
- Review the updated `CHANGELOG.md` files in the PR locally and make any adjustments necessary, then merge the PR into the `release-next` branch.
- Enter Changesets pre-release mode using the `pre` tag:
28
+
-`pnpm changeset pre enter pre`
29
+
- Commit the change and push the `release-next` branch to GitHub
30
+
-`git commit -a -m "Enter prerelease mode"`
31
+
-`git push --set-upstream origin release-next`
32
+
- Wait for the changesets CI workflow to finish which will open a PR pointed to `release-next` that will increment all versions and generate the changelogs
33
+
- If you need/want to make any changes to the `CHANGELOG.md` files, you can do so and commit directly to the PR branch
34
+
- This is usually not required for prereleases
24
35
- Once the changesets files are in good shape, merge the PR to `release-next`
25
-
- Once the PR is merged, the release workflow will publish the updated `X.Y.Z-pre.*` packages to npm.
36
+
- Once the PR is merged, the release workflow will publish the updated `X.Y.Z-pre.*` packages to npm
37
+
38
+
### Prepare the draft release notes
39
+
26
40
- At this point, you can begin crafting the release notes for the eventual stable release in the root `CHANGELOG.md` file in the repo
27
-
- Copy the template for a new release and update the version numbers and links accordingly
41
+
- Copy the commented out template for a new release and update the version numbers and links accordingly
28
42
- Copy the relevant changelog entries from all packages into the release notes and adjust accordingly
- Commit these changes directly to the `release-next` branch - they will not trigger a new prerelease since they do not include a changeset
30
45
31
46
### Iterating a pre-release
32
47
33
48
You may need to make changes to a pre-release prior to publishing a final stable release. To do so:
34
49
35
50
- Branch off of `release-next` and make whatever changes you need
36
-
- Create a new changeset: `pnpm changeset`.
37
-
-**IMPORTANT:** This is required even if you ultimately don't want to include these changes in the logs. Remember, changelogs can be edited prior to publishing, but the Changeset version script needs to see new changesets in order to create a new version.
38
-
- Push your branch to GitHub and PR it to `release-next`.
39
-
- Once reviewed/approved, merge the PR to the `release-next` branch.
40
-
- Wait for the release workflow to finish and the Changesets action to open its PR that will increment all versions.
41
-
- Review the PR, make any adjustments necessary, and merge it into the `release-next` branch.
42
-
- Once the PR is merged, the release workflow will publish the updated `X.Y.Z-pre.*` packages to npm.
51
+
- Create a new changeset: `pnpm changeset`
52
+
-**IMPORTANT:** This is required even if you ultimately don't want to include these changes in the logs. Remember, changelogs can be edited prior to publishing, but the Changeset version script needs to see new changesets in order to create a new version
53
+
- Push your branch to GitHub and PR it to `release-next`
54
+
- Once reviewed/approved, merge the PR to the `release-next` branch
55
+
- Wait for the release workflow to finish and the Changesets action to open its PR that will increment all versions
56
+
- Note: If more changes are needed you can just merge them to `release-next` and this PR will automatically update in place
57
+
- Review the PR, make any adjustments necessary, and merge it into the `release-next` branch
58
+
- Once the PR is merged, the release workflow will publish the updated `X.Y.Z-pre.*` packages to npm
43
59
- Make sure you copy over the new changeset contents into stable release notes in the root `CHANGELOG.md` file in the repo
44
60
45
61
### Publishing the stable release
46
62
47
-
- Exit Changesets pre-release mode in the `release-next` branch: `pnpm changeset pre exit`.
48
-
- Commit the edited pre-release file along with any unpublished changesets, and push the `release-next` branch to GitHub.
49
-
- Wait for the release workflow to finish. The Changesets action in the workflow will open a PR that will increment all versions and generate the changelogs for the stable release.
50
-
- Review the updated `CHANGELOG` files in the PR and make any adjustments necessary.
63
+
- Exit Changesets pre-release mode in the `release-next` branch:
64
+
-`pnpm changeset pre exit`
65
+
- Commit the edited pre-release file along with any unpublished changesets, and push the `release-next` branch to GitHub
66
+
- Wait for the release workflow to finish - the Changesets action in the workflow will open a PR that will increment all versions and generate the changelogs for the stable release
67
+
- Review the updated `CHANGELOG` files in the PR and make any adjustments necessary
- Our automated release process should have removed prerelease entries
53
70
- Finalize the release notes
54
-
- This should already be in pretty good shape in the root `CHANGELOG.md` file in the repo
71
+
- This should already be in pretty good shape in the root `CHANGELOG.md` file in the repo because changes have been added with each prerelease
55
72
- Do a quick double check that all iterated prerelease changesets got copied over
56
-
- Merge the PR into the `release-next` branch.
57
-
- Once the PR is merged, the release workflow will publish the updated packages to npm.
73
+
- Merge the PR into the `release-next` branch
74
+
- Once the PR is merged, the release workflow will publish the updated packages to npm
58
75
- Once the release is published:
59
76
- Pull the latest `release-next` branch containing the PR you just merged
60
77
- Merge the `release-next` branch into `main`**using a non-fast-forward merge** and push it up to GitHub
61
78
-`git checkout main`
62
79
-`git merge --no-ff release-next`
63
80
-`git push origin main`
81
+
-_Note:_ For the `v7.0.0` stable release, there will probably be a bunch of conflicts on `docs/**/*.md` files here because we have made changes to v6 docs but in `dev` we removed a lot of those files in favor of auto-generated API docs. To resolve those conflicts, we should accept the deletion from the `release-next` branch.
64
82
- Merge the `release-next` branch into `dev`**using a non-fast-forward merge** and push it up to GitHub
65
83
-`git checkout dev`
66
84
-`git merge --no-ff release-next`
@@ -72,29 +90,39 @@ You may need to make changes to a pre-release prior to publishing a final stable
72
90
73
91
Hotfix releases follow the same process as standard releases above, but the `release-next` branch should be branched off latest `main` instead of `dev`. Once the stable hotfix is published, the `release-next` branch should be merged back into both `main` and `dev` just like a normal release.
74
92
75
-
### 6.x releases from the `v6` branch
93
+
### v6 releases
76
94
77
-
After the `6.25.0` release, we branched off a `v6` branch for continued `6.x` work and merged the `v7` branch into `dev` to begin preparation for the `7.0.0` release. Until we launch `7.0.0`, we need to `6.x` releases in a slightly different manner.
95
+
6.x releases are managed in a similar process to the above but from the `v6` branch, and they do not automatically merge changes back to `dev`/`main`.
78
96
79
97
- Changes for 6.x should be PR'd to the `v6` branch with a changeset
80
-
- Once merged, cherry-pick or re-do those changes against the `dev` branch so that they show up in v7
81
-
- This does not apply to things like adding deprecation warnings that should not land in v7
82
-
- You should not include a changelog in your commit to `dev`
83
-
- Starting the release process for 6.x is the same as outlined above, with a few changes:
98
+
- If these changes should also be applied to v7, cherry-pick or re-do those changes against the `dev` branch (including the changeset). These changes will make it to `main` with the next v7 release.
99
+
- Starting the release process for 6.x is the same as outlined above, with a few exceptioins:
84
100
- Branch from `v6` instead of `dev`
85
-
- Do not merge `main` into the `release-*` branch
86
-
- The process of the PRs and iterating on prereleases remains the same
101
+
- Use `release-v6` instead of `release-next`
102
+
- Do **not** merge `main` into `release-v6`
103
+
- Steps:
104
+
-`git checkout v6 && git pull origin v6`
105
+
-`git checkout -b release-v6`
106
+
-`pnpm changeset pre enter pre`
107
+
- The process of the PRs and iterating on prereleases remains the same
87
108
- Once the stable release is out:
88
-
- Merge `release-next` back to `v6` with a **Normal Merge**
89
-
- Patch the changes into `main`
109
+
- Merge `release-v6` back to `v6` with a **Normal Merge**
110
+
-**Do not** merge `release-v6` to `main`
111
+
- Copy the updated root `CHANGELOG.md` entries for the `6.X.Y` release to `main` and `dev`
- The _code_ changes should already be in the `dev` branch
124
+
- This should have happened at the time the v6 change was made (except for changes such as deprecation warnings)
125
+
- Confirm that the commits in this release are all included in `dev` already, and if not you can manually bring them over by cherry-picking the commit or re-doing the work
0 commit comments