Skip to content

docs: add interactive release mode documentation #5467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Mar 19, 2025
Merged

docs: add interactive release mode documentation #5467

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
fdb8243
docs: add interactive release mode documentation
cryptodev-2s Mar 12, 2025
1a5b565
docs: remove release summary
cryptodev-2s Mar 13, 2025
d3e5774
Update documentation as per reviews
cryptodev-2s Mar 18, 2025
b527cbf
Merge branch 'main' into cryptodev2s/docs/add-interactive-release-mode
cryptodev-2s Mar 18, 2025
43cf3ac
Add releasing validations examples
cryptodev-2s Mar 18, 2025
20a0716
Update documentation as per second round of reviews
cryptodev-2s Mar 18, 2025
3da6217
Merge branch 'main' into cryptodev2s/docs/add-interactive-release-mode
cryptodev-2s Mar 18, 2025
77f27fc
Update contributing.md
cryptodev-2s Mar 18, 2025
c9823c1
Merge branch 'main' into cryptodev2s/docs/add-interactive-release-mode
cryptodev-2s Mar 18, 2025
de05bad
Merge branch 'main' into cryptodev2s/docs/add-interactive-release-mode
cryptodev-2s Mar 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 44 additions & 1 deletion docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,9 @@ Have changes that you need to release? There are a few things to understand:
- Unlike clients, releases are not issued on a schedule; **anyone may create a release at any time**. Because of this, you may wish to review the Pull Requests tab on GitHub and ensure that no one else has a release candidate already in progress. If not, then you are free to start the process.
- The release process is a work in progress. Further improvements to simplify the process are planned, but in the meantime, if you encounter any issues, please reach out to the Wallet Framework team.

Now for the process itself:
Now for the process itself, you have two options:

### Option A: Manual Release Specification

1. **Start by creating the release branch.**

Expand All @@ -211,6 +213,8 @@ Now for the process itself:

Once you've made the requisite changes to the YAML file, save it and re-run `yarn create-release-branch`. You may need to repeat this step multiple times until you don't see any more errors.

<a id="review-changelogs"></a>

4. **Review and update changelogs for relevant packages.**

Once the tool proceeds without issue, you will be on the new release branch. In addition, each package you intend to release has been updated in two ways:
Expand Down Expand Up @@ -249,6 +253,45 @@ Now for the process itself:

You're done!

### Option B: Interactive Mode
Copy link
Contributor

@mcmire mcmire Mar 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like we are approaching this section by describing the features of this workflow rather than listing a series of steps that people can follow. I know that this workflow will be new to people for a while, but the way this reads currently I worry that people will skip over it.

In addition it seems that we are assuming that people will the section on manually releasing before reading this section on the UI, since we are linking from here to there (effectively jumping backward in the document). I wonder if this is the right way to arrange this section.

In a sense everything described for the manual flow also applies to the UI flow. People will still need to spend a moment to review changes, decide which versions to bump, etc. So maybe we ought to copy the steps listed there to here and then tweak them to fit the UI? Or we can extract step 3 and 4 above to another section.

I'm visualizing the two workflows like this:

flowchart TD
  stepA1[Run 'yarn create-release-branch'];
  stepA2[Modify release spec to specify packages to release];
  stepA3[Close your editor];
  stepA4[Handle errors, reopen the release spec, add more packages as necessary];
  stepB1[Run 'yarn create-release-branch -i'];
  stepB2[Specify packages to release in the UI];
  stepB3[Handle errors and add more packages as necessary via the UI];
  step4[Review and update changelogs];
  step5[Push the branch, create a PR];
  step6[Update the branch with new changes as necessary];

  stepA1 --> stepA2;
  stepA2 --> stepA3;
  stepA3 --> stepA4;
  stepA4 --> step4;
  stepB1 --> stepB2;
  stepB2 --> stepB3;
  stepB3 --> step4;
  step4 --> step5;
  step5 --> step6;
Loading

So perhaps we want to have the steps reflect this?


You can use the interactive web UI to streamline the release process by running:
`yarn create-release-branch -i`

This will:

1. Start a local web server (default port 3000)

2. Open a browser interface showing all packages with changes since their last release

3. Allow you to visually select which packages to include in the release

4. Provide instant validation of your selections, including:

- Identifying packages that need updates when their dependencies are being released
- Flagging packages that need to be included when their peer dependencies are being updated
- Validating version bumps against semantic versioning rules
- Ensuring all necessary dependent packages are included in the release

5. Once your selections are complete, it will directly create the release branch with all necessary version bumps and changelog updates

For example:

- If you're releasing Package A that depends on Package B, the UI will prompt you to include Package B
- If you're releasing Package B with breaking changes, the UI will identify any packages that have peer dependencies on Package B that need to be updated

You can specify a different port if needed:
`yarn create-release-branch -i -p 3001`

The interactive UI simplifies the release process by:

- Providing immediate feedback on your package selections
- Visualizing package dependencies and relationships
- Ensuring complete and valid release configurations
- Eliminating the need to manually edit release specifications

After completing your selections in the UI, proceed to [reviewing and updating changelogs](#review-changelogs).

## Performing operations across the monorepo

This repository relies on Yarn's [workspaces feature](https://yarnpkg.com/features/workspaces) to provide a way to work with packages individually and collectively. Refer to the documentation for the following Yarn commands for usage instructions:
Expand Down
Loading