Merge branch 'trunk'

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2024-05-12
+
+* More documentation
+
+### Added
+
+* Prefix and suffix to tag and release name
+
 ## [0.3.4] - 2024-05-12
 
 * Better documentation

README.md

@@ -20,7 +20,7 @@ As a Template:
 ```yaml
 include:
     -   project: 'swepy/cicd-templates/release-by-changelog'
-        ref: '0.3.4'
+        ref: '0.4.0'
         file: 'templates/release-by-changelog.yml'
 ```
 
@@ -29,7 +29,7 @@ As a Component:
 ```yaml
 # As a Component
 include:
-    -   component: $CI_SERVER_FQDN/swepy/cicd-templates/release-by-changelog/release-by-changelog@0.3.4
+    -   component: $CI_SERVER_FQDN/swepy/cicd-templates/release-by-changelog/release-by-changelog@0.4.0
 ```
 
 ### Customize job
@@ -47,6 +47,81 @@ release-by-changelog:
 
 You can customize the job by overriding the following variables:
 
-| Name                 | Description                        | Default          |
-|----------------------|------------------------------------|------------------|
-| `CHANGELOG_FILEPATH` | The path to the CHANGELOG.md file. | `"CHANGELOG.md"` |
+| Name                 | Description                                   | Default          |
+|----------------------|-----------------------------------------------|------------------|
+| `CHANGELOG_FILEPATH` | The path to the CHANGELOG.md file.            | `"CHANGELOG.md"` |
+| `PREFIX`             | Value to prepend to the tag and release name. |                  |
+| `SUFFIX`             | Value to append to the tag and release name.  |                  |
+| `TAG_PREFIX`         | Value to prepend to the tag.                  | `$PREFIX`        |
+| `TAG_SUFFIX`         | Value to append to the tag.                   | `$SUFFIX`        |
+| `NAME_PREFIX`        | Value to prepend to the release name.         | `$PREFIX`        |
+| `NAME_SUFFIX`        | Value to append to the release name.          | `$SUFFIX`        |
+
+## 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:
+
+```markdown
+# 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](https://pypi.org/project/bump-my-version/), you can
+automate the update of the `Unreleased` section.
+
+To do so, you need this configuration in your `pyproject.toml` file:
+
+```toml
+[[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:
+
+```shell
+bump_my_version bump <MAJOR|MINOR|PATCH>
+```
+
+You'll find a full example of the `bump_my_version`
+configuration [here](pyproject.toml).
+
+### Upcoming and Historical releases
+
+For each release, the version release date MUST be included
+(see [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)). 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](https://docs.gitlab.com/ee/user/project/releases/#upcoming-releases)
+* [Historical releases](https://docs.gitlab.com/ee/user/project/releases/#historical-releases)

pyproject.toml

 [tool.bumpversion]
 commit = true
 config-file = "pyproject.toml"
-current_version = "0.3.4"
+current_version = "0.4.0"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 replace = "{new_version}"
 search = "{current_version}"

templates/release-by-changelog.yml

 release_by_changelog:
     variables:
-        IMAGE_NAME: 'registry.gitlab.com/gitlab-org/release-cli'
-        IMAGE_TAG: 'latest'
-        IMAGE: '$IMAGE_NAME:$IMAGE_TAG'
         CHANGELOG_FILEPATH: 'CHANGELOG.md'
-    image: $IMAGE
+        PREFIX: ''
+        SUFFIX: ''
+        TAG_PREFIX: $PREFIX
+        TAG_SUFFIX: $SUFFIX
+        NAME_PREFIX: $PREFIX
+        NAME_SUFFIX: $SUFFIX
+    image: registry.gitlab.com/gitlab-org/release-cli
     stage: test
     script:
         # Use grep to find version headers and store them in a variable
@@ -55,7 +58,11 @@ release_by_changelog:
         - 'echo "Text:"'
         - 'echo "$text"'
 
+        # Set the tag and name
+        - 'tag="$TAG_PREFIX$version$TAG_SUFFIX"'
+        - 'name="$NAME_PREFIX$version$NAME_SUFFIX"'
+
         # Create the release
-        - 'release-cli create --name "$version" --tag-name "$version" --description "$text" --released-at "$formatted_date"'
+        - 'release-cli create --name "$name" --tag-name "$tag" --description "$text" --released-at "$formatted_date"'
     rules:
         -   if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'