Release Management

In order to release a new version of an application, it is required to combine branching and tagging techniques.

Release Pull Request

• Check out a release branch from the develop branch. Naming for the branch should follow the pattern release/<version number> e.g. release/1.0.0.

• Open a pull request with the release branch as the origin and the main branch as the destination. Naming for the pull request should follow the pattern Release - <version number> e.g. Release - 1.0.0.

• The description of the pull request must abide by this template:

  

  • On the first line, include the link to the GitHub milestone or the release on the project management tool to make it easier for reviewers to get the complete requirements:

    # GitHub milestone
    https://github.com/nimblehq/git-templates/milestone/41?closed=1
        
    # Shortcut
    https://app.shortcut.com/acme/label/12345
    

  • Features: provide the list of features in the release.
  • Chores: provide the list of chores in the release.
  • Bugs: provide the list of bugs fixes in the release.

• Once the pull request is approved and the test suite has run successfully, merge the release branch.

Tagging

Once the code is merged into the main branch, keep track of versions by using Git tags.

• Add a tag locally corresponding to the version released from the main branch e.g. git tag -a 1.0.0.

• Add a changelog in the commit message for the tag following this convention when entering the interactive mode:

  • List changes as a bullet point list

  • Group changes into sections for each issue type:

    ## Features
    - [ch682] As a user I can view the list of job positions (#125)
    - [ch683] As a user I can view the details of a job position (#128)
          
    ## Bugs
    - [ch688] Fix: Login with LinkedIn (#126)
          
    ## Chores
    - [ch678] Set up staging environment (#127)
    

    Having the pull request ID is preferred but not compulsory. On GitHub, the ID is parsed and linked to the pull request making is useful.

• Push the newly added tag to the remote with git push --tags.

Close Milestone

GitHub (or GitLab) supports milestones to track progress on groups of issues or pull requests for a release. The team uses milestones to manage stories for a release by naming them the same as the release version.

Since there can potentially be multiple milestones at the same time, developers need to ensure the corresponding milestone for the released version is closed.

Create Release Package

Once the new version tag is created on the main branch, the developer must also make a corresponding GitHub (or GitLab) release to package software, along with release notes and links to binary files, for other people to use.

To publish a release package, here are good guidelines on how to manage release on the following supported Git platforms:

• GitHub - Managing releases in a repository
• GitLab - Releases

The description of the release note needs to abide by the same template as the release pull request. At the same time, there are some contrarieties such as:

• Each item can use the format of the generated content instead.

• New sections can be introduced to match the story types of the repositories, for example:

  ## Content
  - [#76] Add Production > Monitoring by @olivierobert in https://github.com/nimblehq/compass/pull/1130
  - Harmonize automated testing across all platforms by @olivierobert in https://github.com/nimblehq/compass/pull/1134
  - Revamp the Developer Track content - Technical Lead - level 8 by @sleepylee in https://github.com/nimblehq/compass/pull/1131
    
  ## Features
  `N/A`
    
  ## Chores
  - Bump nokogiri from 1.13.9 to 1.13.10 by @dependabot in https://github.com/nimblehq/compass/pull/1137
    
  ## Bugs
  `N/A`