Skip to content

docs(release): add release process guide for internal contributors #19543

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

Open
jrainville wants to merge 2 commits into
base: master
Choose a base branch
from
+75 −0
Open

docs(release): add release process guide for internal contributors #19543

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bcddcf7
docs(release): add release process guide for internal contributors
jrainville Dec 9, 2025
6204fc0
docs(release): clarify who must cherry-pick
jrainville Dec 10, 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
8 changes: 8 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
- [Contributing to the Status App](#contributing-to-the-status-app)
- [Table of Contents](#table-of-contents)
- [🛠️ Developing](#️-developing)
- [Internal guides](#internal-guides)
- [🪲 Status App Community Testing](#-status-app-community-testing)
- [Disclaimer](#disclaimer)
- [**🛠️ Testing Instructions for Status Release Candidate Build**](#️-testing-instructions-for-status-release-candidate-build)
Expand All @@ -25,6 +26,13 @@
- Check out [good first issues](https://github.com/status-im/status-app/contribute) to get involved.
- Join the [#feedback-desktop](https://status.app/cc/G-EAAORobqgnsUPSVCLaSJr855iXTIdQiY1Q0ckBe8dWWEBpUAs9s8DTjWEpvsmpE83Izx1JWQuZrWWKUoxiXCwdtB-wPBzyvv_n9a0F61xTaPZE7BEJDC7Ly_WcmQ4tHRAKnPfXE_JUtEX_3NhnXQN0eh4ue0D77dWvaDpDrSi0U0CaGLZ-pqD_iV0z9RMFE2LKulDZdwL40etJ8lxjyTFoxS0lUhdWKinIOk8qBmJJpCmsqMrSklEU#zQ3shZeEJqTC1xhGUjxuS4rtHSrhJ8vUYp64v6qWkLpvdy9L9) and [#feedback-mobile](https://status.app/cc/G-EAAOTgmsumqFvQZ-DSRkmf6xZuG-jQBrqnB6ytivISS1qeYURpfrzeMMePtpp7Inw_qy_cLdpZLJNUgOmfMHIZ4n2zSTr-n9u34C4yZa7c4JGLz9U6GIfjPqa0J0Ng2GC_Pu76QxgM-1v0z8V0PxxAf3fdHNbQXy-vfqWhK2iF0E6AaaJMh3sCmp_YpfFwR0DPmDIORPwdI_5ot4VZpkSb9FCkBwJO0xKNc5zI4oYpjfAhZVAyNWIHJs0D#zQ3shZeEJqTC1xhGUjxuS4rtHSrhJ8vUYp64v6qWkLpvdy9L9) channels on Status.

### Internal guides

These guides are meant to be used by internal contributors. If you're an external contributor, you can also read them to get a sense of how we work, but you do not have to apply those guidelines.

- [Release Process Guide](/docs/internal/release-process.md)
- Dev-Design-Product-QA Workflow (Comming soon)

## 🪲 Status App Community Testing

### Disclaimer
Expand Down
3 changes: 3 additions & 0 deletions docs/internal/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Internal Guides

This section is meant for internal contributors. Not because they are private, just because external contributors don't need to follow those guidelines.
64 changes: 64 additions & 0 deletions docs/internal/release-process.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Release Process Guide

This guide is meant to explain the flow and rules of the release process, ie the period when we cut a release branch off the master branch in prevision of releasing it to users. Release Candidates (RC) are provided to test the Release.

1. A release branch **must** be created at the start of the Release Process for the [Status App](https://github.com/status-im/status-app)'s master branch and [status-go](https://github.com/status-im/status-go)'s develop branch
1. The format for the status-app branch is `release/MAJOR.MINOR.x`, eg. `release/2.36.x`
2. The format for the status-go branch is automatically done using the Release script. Ask a status-go maintainer to create it.
3. The status-app release branch **must** always point to the status-go release branch.

2. Issues needing to be fixed on the RC **must** be added to the [Release Board](https://github.com/orgs/status-im/projects/97/views/1).

3. Only bug fixes **must** be provided to the release branch.

4. Moreover, only **critical** bug fixes **should** be added to the [Release Board](https://github.com/orgs/status-im/projects/97/views/1) and committed to the release branch.
1. Critical bugs are issues that affect the **behaviour** of the features.
2. This includes regressions to previously working features (eg: removing an emoji reaction no longer works).
3. This also includes issues breaking new features, ie **not** according to the expected Acceptance Criteria (eg: Browser is expected to allow saving bookmarks and the feature does not work).

5. One or more Testing days **should** be done by the entire Status team to find any regressions.
1. The Status team **should** split in testing groups to help test features.
2. Testing groups **should** contain people from different teams to spread the knowledge.
3. Testing days **must** use a list of current features to test.
4. The list **should** include a column listing issues found and by whom.
5. The list **should** include an indicator whether that feature is covered by end-to-end (e2e) test and/or functional tests.
6. The list **should** contain a section documenting which features were recently **added** or **refactored**.
7. The recently added or refactored features **should** be the most tested.
8. Features on the list **can** be tested by multiple testing groups.

6. Regressions **should** be mentioned to the QA team so that they can plan and implement e2e tests to prevent further regressions of the sorts (to be implemented on master).

7. Code coverage does **not** need to be met on the release branch.

8. Features **must not** be allowed to be added to the release branch under any circumstances.

9. Fixes for issues identified during the RC phase **must** be worked on and committed on the release branch **first**.

10. Once a fix has been applied to the release branch, it **must** be ported to the master branch by the author of the commit.

11. A new RC build **can** be triggered every day, if there are new fixes in the release branch.


## Frequently asked questions

### When is a release ready to be cut?

A release is considered ready to be cut when all **Key** features are **Done**.

A **Key** feature is a feature identified on the [Roadmap](https://github.com/status-im/status-app/blob/master/docs/roadmap.md) as the most important features for that release.

A feature is considered **Done** when all issues of its Epic are closed. An Epic **must** include a testing issue, where one of the dev who worked on the issue meets with one of the designers and/or the Product Manager to demo the issue. Designers and/or the PM **should** open any issue they find on the new feature.

#### What happens to the other features not ready at the time of the release cut?

The remaining features listed on the [Roadmap](https://github.com/status-im/status-app/blob/master/docs/roadmap.md) on the same milestone, but that were not identified as **key**, will simply be pushed to the next milestone.

All new features **must** implement a **feature flag**. Therefore, unfinished features **must not** affect master and the release.

### Why commit to the release branch first and not master?

1. It is faster for the release.
2. Less possibilities of conflicts on the release branch.
3. Cherry-picked commits are often **not** tested. That is acceptable on master, but **unacceptable** on the release branch.
4. Issues do **not** close as completed when merged on the release branch. Therefore, it is easy to spot that the commit needs to be cherry-picked to master.