feat(process): document the release process with a mermaid diagram #146

gauthierpetetin · 2025-08-29T08:49:00Z

CLICK HERE to preview the release process diagram

XxdpavelxX

Looks great. Thanks a lot Gauthier

XxdpavelxX · 2025-08-29T13:01:36Z

docs/release-process.md

+end
+
+subgraph Previous [Previous release branch: 'release/x.y-1.z']
+    style Previous fill:#08084d,stroke:#000,stroke-width:2px,color:#fff


It's a bit hard to see the lines and where they're pointing in the dark blue background. Can we change the color of that background square or lines so that they're more visible?

Mmh.. for me it was the opposite, I had to use dark background colors on purpose in order to see the white arrows. Are the arrows not white on you side?

Looks a lot better in that screenshot. Maybe I was looking in the wrong place. Did you do anything or navigate somewhere to see it like that?

XxdpavelxX

Looks good, although it appears that the top right side square where it says "Previous Release Branch:" and "Hotfix Release Branch:" was cut off.

XxdpavelxX · 2025-09-04T13:52:17Z

docs/release-process.md

+    HOTFIX1 -->|every time a release is merged into 'stable'| CURRENT4
+    CURRENT4 --> CURRENT5[Changelog is added]
+    CURRENT5 --> CURRENT6[Release is tested by all teams]
+    CURRENT7[Release Engineer cherry-picks fixes on 'release/x.y.z' branch]


We mentioned cherry picks today during part of the release process. Does the cherry picking only happen during a hotfix?

Do we update the changelog again after this as well?

We do cherry picks every time code needs to be added to a release branch after the initial release branch creation.

Example:

Release branch is created for release x.y.z

We test the release and find a bug

Bug is fixed on main branch

Then we cherry-pick the fix on the release branch

Then we update the changelog accordingly on the release branch

So cherry-picks happen for any kind of releases, not only hotfixes.

XxdpavelxX · 2025-09-04T13:54:50Z

docs/release-process.md

+    style Current fill:#08084d,stroke:#000,stroke-width:2px,color:#fff
+    MAIN1 -->|every 2 weeks| CURRENT1[Runway automatically creates a new release branch based off of 'main' branch, called 'release/x.y.z']
+    CURRENT1 --> CURRENT2[GitHub Action creates x.y.z release PR]
+    CURRENT2 -->|every time a commit is added to 'release/x.y.z' branch| CURRENT3[Release build is automatically created and posted on the x.y.z release PR]


every time a commit is added to 'release/x.y.z' branch| CURRENT3[Release build is automatically created and posted on the x.y.z release PR. How is this release build automatically created? Is there a separate GH actions workflow for this?

The release build is automatically created by the publish-prerelease.yml GitHub Action

XxdpavelxX · 2025-09-04T13:58:24Z

docs/release-process.md

+    MAIN1 -->|every 2 weeks| CURRENT1[Runway automatically creates a new release branch based off of 'main' branch, called 'release/x.y.z']
+    CURRENT1 --> CURRENT2[GitHub Action creates x.y.z release PR]
+    CURRENT2 -->|every time a commit is added to 'release/x.y.z' branch| CURRENT3[Release build is automatically created and posted on the x.y.z release PR]
+    CURRENT3 --> CURRENT4[Release Engineer creates and merges stable sync PR into 'release/x.y.z branch']


What is the "stable sync PR"? What branch is being merged in the "release/x.y.z" branch here?

Every time code is added to stable branch, we need to merge stable into main and into all branches that have stable as base branch, like the release/x.y.z branches. Otherwise, they'd be out of sync with stable.

Example:
After release 13.2.1 got merged to stable last week, we've opened 2 stable sync PRs

Stable sync to main (usually, only updates to the changelog file)

Stable sync to 13.3.0 release branch

XxdpavelxX · 2025-09-04T13:58:56Z

docs/release-process.md

+    CURRENT2 -->|every time a commit is added to 'release/x.y.z' branch| CURRENT3[Release build is automatically created and posted on the x.y.z release PR]
+    CURRENT3 --> CURRENT4[Release Engineer creates and merges stable sync PR into 'release/x.y.z branch']
+    PREVIOUS1 -->|every time a release is merged into 'stable'| CURRENT4
+    HOTFIX1 -->|every time a release is merged into 'stable'| CURRENT4


Is this merging the release branch into the stable branch?

XxdpavelxX · 2025-09-04T14:00:18Z

docs/release-process.md

+    CURRENT3 --> CURRENT4[Release Engineer creates and merges stable sync PR into 'release/x.y.z branch']
+    PREVIOUS1 -->|every time a release is merged into 'stable'| CURRENT4
+    HOTFIX1 -->|every time a release is merged into 'stable'| CURRENT4
+    CURRENT4 --> CURRENT5[Changelog is added]


Is this referring to the changelog.md file?

Also, Where is it added? Is it added to release branch or somewhere else?

Yes this is referring to the changelog.md file.
It is added to the release branch.

Example for release 13.3.0: MetaMask/metamask-extension#35523

XxdpavelxX · 2025-09-04T14:10:37Z

docs/release-process.md

+    MAIN1[All changes are first made on 'main' branch]
+end
+
+subgraph Previous [Previous release branch: 'release/x.y-1.z']


Looks like this is getting cut off a bit in the diagram. Can we move it a little?

Unfortunately I don't think we can easily move choose texts' positions on a mermaid diagram (at least I didn't figure out how to).

XxdpavelxX · 2025-09-04T14:11:01Z

docs/release-process.md

+    PREVIOUS2 -->|merge PR| MAIN1
+end
+
+subgraph HotFix [Hotfix release branch: 'release/x.y-1.z+1']


Looks like this is getting cut off a bit in the diagram as well. Can we move it a little?

Unfortunately I don't think we can easily move choose texts' positions on a mermaid diagram (at least I didn't figure out how to).

XxdpavelxX · 2025-09-04T14:12:45Z

docs/release-process.md

+subgraph Previous [Previous release branch: 'release/x.y-1.z']
+    style Previous fill:#08084d,stroke:#000,stroke-width:2px,color:#fff
+    PREVIOUS1[Previous release is merged into 'stable' branch]
+    PREVIOUS1 -->|create PR| PREVIOUS2[Release Engineer creates stable sync PRs]


Just for context, what is a "stable sync PR"? Which branch is being synced with stable?

More context here

XxdpavelxX · 2025-09-04T14:14:42Z

docs/release-process.md

+FEAT -->|merge PR| MAIN1
+
+%% Subgraphs %%
+subgraph Main [Main developement branch: 'main']


Are we still generating commits.csv as part of the release process or was that deprecated? If used where does it come into play?

We only need commits.csv to generate the changelog PR in the create-release-pr GitHub Action.

XxdpavelxX · 2025-09-04T14:16:37Z

docs/release-process.md

+CURRENT6 --> BUG1[A bug is found]
+BUG1 --> BUG2[A fix is done on 'main' branch]
+BUG2 --> CURRENT7
+ENG[Engineer] -->|create PR| FEAT[Implement new features]


I think we mentioned it during the meeting today but is package.json in the main branch used for something in the release process?

The release version indicated in package.json is used by an automation that fills the release spreadsheet every time a PR gets merged.

feat(process): document the release process with a mermaid diagram

a321e72

gauthierpetetin self-assigned this Aug 29, 2025

gauthierpetetin requested a review from a team as a code owner August 29, 2025 08:49

fix(note): there are multiple release branches

5443a13

XxdpavelxX reviewed Aug 29, 2025

View reviewed changes

fix(note): update inaccurate connexion

d6319f8

XxdpavelxX approved these changes Sep 3, 2025

View reviewed changes

XxdpavelxX reviewed Sep 4, 2025

View reviewed changes

kathleenmotley49-maker approved these changes Sep 5, 2025

View reviewed changes

Uh oh!

feat(process): document the release process with a mermaid diagram #146

Are you sure you want to change the base?

feat(process): document the release process with a mermaid diagram #146

Uh oh!

Conversation

gauthierpetetin commented Aug 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

XxdpavelxX left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

XxdpavelxX left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gauthierpetetin Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gauthierpetetin Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gauthierpetetin commented Aug 29, 2025 •

edited

Loading

XxdpavelxX left a comment •

edited

Loading

XxdpavelxX left a comment •

edited

Loading

gauthierpetetin Sep 8, 2025 •

edited

Loading

gauthierpetetin Sep 8, 2025 •

edited

Loading