From 5d36704bb67f5a1b17bc8456ad2f5c842c392a5f Mon Sep 17 00:00:00 2001 From: Matt Brophy Date: Wed, 18 Dec 2024 10:51:38 -0500 Subject: [PATCH] Update DEVELOPMENT.md --- DEVELOPMENT.md | 56 ++++++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 29 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 6c08ccc786..cc737ba1dd 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -2,26 +2,34 @@ ## Releases -New releases should be created from release branches originating from the `dev` branch. When you are ready to begin the release process: +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. + +When you are ready to begin the release process: - Make sure you've pulled all the changes from GitHub for both `dev` and `main` branches + - `git checkout main && git pull origin main` + - `git checkout dev && git pull origin dev` - Check out the `dev` branch -- Create a new `release-next` branch (eg, `git checkout -b release-next`) + - `git checkout dev` +- Create a new `release-next` branch + - `git checkout -b release-next` - 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` - - We are using `release-v6` for [ongoing v6 releases](#6x-releases-from-the-v6-branch) -- Merge `main` into the release branch + - We are using `release-v6` for [ongoing v6 releases](#v6-releases) +- Merge `main` into the `release-next` branch + - `git merge --no-ff main` 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. ### Starting a new pre-release - Ensure you are on the new `release-next` branch + - `git checkout release-next` - Enter Changesets pre-release mode using the `pre` tag: - `pnpm changeset pre enter pre` - Commit the change and push the `release-next` branch to GitHub - `git commit -a -m "Enter prerelease mode"` - `git push --set-upstream origin release-next` -- Wait for the release workflow to finish - the Changesets action will open a PR that will increment all versions and generate the changelogs +- 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 - If you need/want to make any changes to the `CHANGELOG.md` files, you can do so and commit directly to the PR branch - This is usually not required for prereleases - Once the changesets files are in good shape, merge the PR to `release-next` @@ -30,7 +38,7 @@ Changesets will do most of the heavy lifting for our releases. When changes are ### Prepare the draft release notes - At this point, you can begin crafting the release notes for the eventual stable release in the root `CHANGELOG.md` file in the repo - - Copy the template for a new release and update the version numbers and links accordingly + - Copy the commented out template for a new release and update the version numbers and links accordingly - Copy the relevant changelog entries from all packages into the release notes and adjust accordingly - `find packages -name 'CHANGELOG.md' -mindepth 2 -maxdepth 2 -exec code {} \;` - Commit these changes directly to the `release-next` branch - they will not trigger a new prerelease since they do not include a changeset @@ -82,23 +90,25 @@ You may need to make changes to a pre-release prior to publishing a final stable 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. -### 6.x releases from the `v6` branch +### v6 releases -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. +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`. - Changes for 6.x should be PR'd to the `v6` branch with a changeset -- Once merged, cherry-pick or re-do those changes against the `dev` branch so that they show up in v7 - - This does not apply to things like adding deprecation warnings that should not land in v7 - - You should not include a changeset in your commit to `dev` -- Starting the release process for 6.x is the same as outlined above, with a few changes: +- 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. +- Starting the release process for 6.x is the same as outlined above, with a few exceptioins: - Branch from `v6` instead of `dev` - - Use the name `release-v6` to avoid collisions with the ongoing v7 (pre)releases using `release-next` - - **Do not** merge `main` into the `release-v6` branch -- The process of the PRs and iterating on prereleases remains the same + - Use `release-v6` instead of `release-next` + - Do **not** merge `main` into `release-v6` +- Steps: + - `git checkout v6 && git pull origin v6` + - `git checkout -b release-v6` + - `pnpm changeset pre enter pre` + - The process of the PRs and iterating on prereleases remains the same - Once the stable release is out: - Merge `release-v6` back to `v6` with a **Normal Merge** - **Do not** merge `release-v6` to `main` - - Copy the updated root `CHANGELOG.md` entry for the `6.X.Y` release to `main` and `dev` + - Copy the updated root `CHANGELOG.md` entries for the `6.X.Y` release to `main` and `dev` - `git checkout main` - `git diff react-router@6.X.Y...react-router@6.X.Y -- "***CHANGELOG.md" > ./docs.patch` - `git apply ./docs.patch` @@ -112,19 +122,7 @@ After the `6.25.0` release, we branched off a `v6` branch for continued `6.x` wo - `rm ./docs.patch` - The _code_ changes should already be in the `dev` branch - This should have happened at the time the v6 change was made (except for changes such as deprecation warnings) - - Confirm that the commits in this release are all included in `dev` already: - - I.e., https://github.com/remix-run/react-router/compare/react-router@6.26.1...react-router@6.26.2 - - If one or more are not, then you can manually bring them over by cherry-picking the commit (or re-doing the work) - - You should not include a changelog in your commit to `dev` - - Copy the updated changelogs from `release-next` over to `dev` so the changelogs continue to reflect this new 6x release into the v7 releases - -### Notes on 7.0.0-pre.N released during the v7 prerelease - -During the v7 prerelease, the process for iterating and shipping a new `7.0.0-pre.N` release is slightly more streamlined than the steps outlined [above](#iterating-a-pre-release). Because we want _everything_ in `dev` to ship in the prerelease, cutting a new prerelease is simply: - -- Merge `dev` -> `release-next` -- This will include the changesets for changes committed to `dev` since the last prerelease -- This will automatically open a new Changesets PR for the new prerelease version + - 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 ### Experimental releases