Release By Changelog template

Objective

Publish a new release based on the content of the CHANGELOG.md file. The file must follow the Keep a Changelog format and each release must adhere to Semantic Versioning.

How to use it

Include the component/template

Add the following to your .gitlab-ci.yml file.

As a remote Template (recommended):

include:
    -   remote: 'https://gitlab.com/swepy/cicd-templates/release-by-changelog/-/raw/0.4.3/templates/release-by-changelog.yml'

As a local Template (if the template is local to the instance):

include:
    -   project: 'swepy/cicd-templates/release-by-changelog'
        ref: '0.4.3'
        file: 'templates/release-by-changelog.yml'

As a Component (beta and if the component is local to the instance):

include:
    -   component: $CI_SERVER_FQDN/swepy/cicd-templates/release-by-changelog/release-by-changelog@0.4.3

Customize job

You can customize the job by overriding specific keys. For example:

release-by-changelog:
    stage: release
    variables:
        CHANGELOG_FILEPATH: "docs/CHANGELOG.md"

Variables

You can customize the job by overriding the following variables:

About CHANGELOG.md

Unreleased changes

The CHANGELOG.md file may have an Unreleased section at the top of the file. This section is used to keep track of changes that are not yet released.

Example:

# Changelog

## [Unreleased]

* Add new feature

## [1.0.0] - 2020-01-01

* First release

Bump the version

When the release is ready, the Unreleased section must be moved to a new version section and the version number must be bumped.

If you are using bump_my_version, you can automate the update of the Unreleased section.

To do so, you need this configuration in your pyproject.toml file:

[[tool.bumpversion.files]]
filename = "CHANGELOG.md"
replace = """## [Unreleased]

## [{new_version}] - {now:%Y-%m-%d}
"""
search = """## [Unreleased]
"""

Then you can bump the version by running the following command:

bump_my_version bump <MAJOR|MINOR|PATCH>

You'll find a full example of the bump_my_version configuration here.

Upcoming and Historical releases

For each release, the version release date MUST be included (see Keep a Changelog). This date is used to define the release date in the GitLab release. If the date is the same as the current date when the job runs, the release exact time is defined by gitlab. Otherwise, the release time is set to 00:00:00 UTC and the release will carry a badge as historical or upcoming.

• For upcoming releases, the badge will be removed when the release is published.
• For historical releases, the badge will remain, and release evidences won't be available.

See:

• Upcoming releases
• Historical releases