Prerelease Version Procedure

[CMCDragonkai]

Sometimes we need to do pre-releases from feature branches for debugging and testing.

Remember that major, minor and patch release are done from the staging branch.

First we merge staging into master and if the CI passes, then at that point we can create a release tag on the staging branch.

This is simply:

npm version major
npm version minor
npm version patch

Then we push up:

git push --follow-tags

Sometimes we want to trigger the CI faster, then do this:

git remote add cicd git@gitlab.com:MatrixAI/open-source/<project>.git
git push --follow-tags
git push --follow-tags cicd

However on feature branches, the procedure is as follows:

npm version prepatch --preid "$(git branch --show-current)"

If you are currently on 1.1.5, this will produce:

1.1.6-feature-hello-world.0

If you do this repeatedly it will produce:

1.1.6-feature-hello-world.0
1.1.6-feature-hello-world.1
1.1.6-feature-hello-world.2

This ensures that any releases here always comes after 1.1.5 in semantic versioning order.

Once the feature branch is ready, it can be merged to staging.

When you are back on staging, you can again make a decision as to whether to use:

npm version major # backwards compatibility is broken
npm version minor # backwards compatibility is maintained, but new features
npm version patch # interface stays the same, encapsulated changes

If you use npm version patch, it produces 1.1.6, and 1.1.6 will be higher than the 1.1.6-feature-hello-world.X.

Doing this does require some discipline to avoid problems, remember tags are immutable by default.

Tasks

• 1. Write up release and prerelease procedure into development documentation

[tegefaulkes]

Note that doing this with a preid that include a _ breaks the command when you try to run it multiple times. So branch names that include _ can't work with this.

In the future I'll avoid using _ in branch names.

[CMCDragonkai]

Yea I always used feature-x as the branch names.

[CMCDragonkai]

I think all preids should be kept as alpha, beta or rc.

The terms "alpha," "beta," and "release candidate" (rc) are commonly used in the software development life cycle to denote different stages of software maturity. However, these are more traditional norms and guidelines rather than strict rules. Here's a general framework:

1. Alpha: This is often the first phase where the feature set is complete but likely to contain a number of known or unknown bugs. Stability, performance, or other attributes may not meet the standards for a production release. Use this stage for initial testing, understanding limitations, and getting early feedback.

2. Beta: At this point, the software has gone through various alpha iterations and is considered feature complete and relatively stable but may still have bugs. It is intended for external testing and broader feedback. It often precedes a full-scale, public beta test and is intended for a restricted audience under real-world conditions.

3. Release Candidate (RC): This version is considered to be stable and is a candidate for production release. Unless significant bugs are discovered, this version will be turned into the production release. An RC version may go through multiple iterations before it becomes the final version.

Considerations for Decision Making:

• Feature Completeness: Are all planned features implemented? If not, you're likely in alpha. If yes, you could be in beta or RC.

• Stability: How stable is your application? Frequent crashes suggest you're in the alpha stage. Lesser but still significant issues could imply a beta stage. If you're confident about the system's stability, you may be ready for an RC.

• User Feedback: Are you looking for general user feedback on functionality and features, or are you in the final stages of testing and just verifying that there are no last-minute issues? The former leans towards beta, and the latter towards RC.

• Timeline: Is your release date flexible or fixed? If you have time to iterate, you might be in alpha or beta. If you're close to your release date, you're likely in the RC phase.

• Bug Count & Severity: A high number of severe known bugs usually indicates you're still in alpha. Fewer, less critical bugs might suggest beta. Minimal, non-critical bugs could indicate you're at the RC stage.

Remember, the goal is not just to slap on a label, but to communicate effectively with your stakeholders. Choose the term that will set their expectations most accurately.

[CryptoTotalWar]

This Ticket will likely be a sub-ticket for the contributor guide documentation ticket.

Moving to backlog.

Tasks

• Evaluate where this information belongs in the developer documentation via check-in W/Brian
  • Assign as a sub-ticket to that category