development-guidelines/release-delivery.md

• Introduction
• Branch Types
  • Trunk Branch
  • Topic Branches
• Contribution Rules
• Instructions
  • Create a New Feature
  • Manage Hotfixes
  • Undo Mistakes
  • Manage Releases
• Limitations
  • Parallel release branches are not supported.

Introduction

We take a similar approach to GitHub flow for our projects that are delivered through releases.

Branch Types

There are two branch types:

• trunk
• topic

Trunk Branch

The trunk is your development branch, the only long-lived branch in your remote server. Use main for the name of this branch across all projects for consistency. It will contain your recent well-tested merged changes and must always be release-ready. No one is allowed to push to this branch directly.

Topic Branches

Contributors will work on short-lived branches and push their changes to the remote server on a branch with the same name. They should then create a request for merging the branch into the trunk. The maintainer(s) may accept the request after reviewing the changes and when all the tests are passed to ensure nothing will break on the trunk branch by merging.

%%{init: { 'theme': 'base', 'gitGraph': {'showCommitLabel':false,'mainBranchOrder': 0}} }%%
      gitGraph
      commit tag: "v1.0.0"
      branch topic-foo
      checkout topic-foo
      commit
      commit
      checkout main
      merge topic-foo
      commit tag: "v1.1.0"
      branch topic-fix
      commit
      checkout main
      merge topic-fix
      commit tag: "v1.1.1"

Contribution Rules

You should strictly follow the Contribution Rules document.

Instructions

Create a New Feature

1. Create a local branch:

$ git checkout -b topic-foo main

2. Push your changes to a remote branch with the same name:

$ git push origin topic-foo

3. Create a merge request from your new branch to the main branch.

4. Delete your branch after your merge request is approved.

Manage Hotfixes

We treat a hotfix the same as other topic branches; see the instruction for creating a new feature.

Undo Mistakes

TODO.

Release Types

Releases should be of the following types:

Alpha: Intended for internal use. These are early-stage versions that might have incomplete features or known bugs. They serve as the initial testing phase for new functionalities.

Beta: Think of these as our MVP (Minimum Viable Product) versions. They are more polished than alpha versions, better tested, but might still have a few edges to smooth out.

Full Releases (v1, v2, ...): The polished and full-featured versions, all set and stable.

We can also group them by pre-release (alpha, beta) and full release (v1, v2, ...).

Manage Releases

You must automate the process of creating releases and publishing them to repository servers. But triggering the release action should be done manually by the project's maintainer(s), whether by running a script locally or using CI services like GitHub Actions.

By triggering a release, a script will:

1. Decide on a version name based on the commits history since the last release
2. Update the changelog file
3. Update the code with the new version name and the local dependencies in monorepos.
4. Run tests and build the software/packages to make sure everything works well
5. Commit changes on the trunk
6. Create a tag off the trunk with the new version name
7. Push the trunk and the new tag to the remote repository
8. Publish packages to repository servers.

Limitations

Parallel release branches are not supported.

Developing multiple versions is not supported in this strategy; as a consequence, you will not be able to release a patch for older major and minor versions, so keep in mind to avoid introducing breaking changes as far as possible.