diff --git a/.bumpversion.toml b/.bumpversion.toml
index a9d68f47614a703918e86cee5335c9646287ccf3..783425c1b9519134828548cf15ea2ebdb5d4cd61 100644
--- a/.bumpversion.toml
+++ b/.bumpversion.toml
@@ -1,6 +1,6 @@
[tool.bumpversion]
commit = true
-current_version = "0.4.7"
+current_version = "1.0.0"
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
replace = "{new_version}"
search = "{current_version}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 95186dbbcaf8b2c7cb67a78ba5bfda6a5fdd8188..94a8cf0fc33f7fb50a452f4dd627f227fb0129f8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+## [1.0.0] - 2024-08-04
+
+### Added
+
+* Support of [inputs](https://docs.gitlab.com/ee/ci/yaml/inputs.html)
+* Complete revamp of the documentation
+
## [0.4.7] - 2024-08-04
* Misc update of the project
diff --git a/README.md b/README.md
index 64a0b30169bac64702c63aa7bcef7fa4be48a9c6..db0adc1d7d29afb915325b2e132c9d70f7363d04 100644
--- a/README.md
+++ b/README.md
@@ -1,70 +1,105 @@
# Release By Changelog
-[](https://lab.frogg.it/swepy/cicd-templates/release-by-changelog/-/blob/main/LICENSE)
+ [](https://lab.frogg.it/swepy/cicd-templates/release-by-changelog/-/blob/main/LICENSE) [](https://gitlab.com) [](https://froggit.fr/)
-## Objective
-Publish a new release based on the content of the `CHANGELOG.md` file.
-The file must follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
-format and each release must adhere
-to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## Goal
+
+Publish a new release based on the content of the `CHANGELOG.md` file in less than 10 seconds. The file must follow the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format and each release must adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## How to use it
-### Include the component/template
+Add the following to your `.gitlab-ci.yml` file:
+
+### For gitlab.com and mirrored instance
+
+```yaml
+include:
+ - component: $CI_SERVER_FQDN/swepy/cicd-templates/release-by-changelog/release-by-changelog@1.0.0
+```
+
+> âš ï¸ On gitlab <16.10, use `$CI_SERVER_FQDN:$CI_SERVER_PORT` instead of `$CI_SERVER_FQDN`.
+
+When referencing a CI/CD catalog component, you can use a special format to specify the latest semantic version in a range. [Read more about Semantic version ranges](https://docs.gitlab.com/ee/ci/components/#semantic-version-ranges).
+
-Add the following to your `.gitlab-ci.yml` file.
+[](https://gitlab.com) [](https://froggit.fr/)
-As a Component (recommended) if the component is supported
-or [mirrored](https://docs.gitlab.com/ee/user/project/repository/mirror/pull.html) by
-your instance:
+### Self-hosted instance
+
+For self-hosted instances, you need to import the component as a remote template.
```yaml
include:
- - component: $CI_SERVER_FQDN/swepy/cicd-templates/release-by-changelog/release-by-changelog@0.4.7
+ - remote: 'https://gitlab.com/swepy/cicd-templates/release-by-changelog/-/raw/1.0.0/templates/release-by-changelog.yml'
```
-[](https://gitlab.com)
-[](https://froggit.fr/)
+If you want to use semantic version ranges, you need to do a [mirror](https://docs.gitlab.com/ee/user/project/repository/mirror/pull.html) of the repository and rely on the component include.
+
+### Customize
+
+You can configure the component/template using [inputs](https://docs.gitlab.com/ee/ci/yaml/inputs.html).
-As a remote Template if the component is not supported or mirrored by your instance:
+Available inputs:
+
+| Name | Description | Default |
+|-----------------------|-----------------------------------------------|----------------|
+| `stage` | The stage of the job. | `deploy` |
+| `changelog file path` | The path to the `CHANGELOG.md` file. | `CHANGELOG.md` |
+| `suffig` | Value to prepend to the tag and release name. | `""` |
+| `prefix` | Value to append to the tag and release name. | `""` |
+
+Example of configuration with local component:
+
+```yaml
+include:
+ - component: $CI_SERVER_HOST/swepy/cicd-templates/release-by-changelog/release-by-changelog@1.0.0
+ inputs:
+ stage: release
+ prefix: version-
+```
+
+Example of configuration with remote template:
```yaml
include:
- - remote: 'https://gitlab.com/swepy/cicd-templates/release-by-changelog/-/raw/0.4.7/templates/release-by-changelog.yml'
+ - remote: 'https://gitlab.com/swepy/cicd-templates/release-by-changelog/-/raw/1.0.0/templates/release-by-changelog.yml'
+ inputs:
+ stage: release
+ prefix: version-
```
-### Customize job
+#### Further configuration
-You can customize the job by overriding specific keys. For example:
+Using variables, you have access to more granular configuration. Example:
```yaml
+include:
+ - component: $CI_SERVER_FQDN/swepy/cicd-templates/release-by-changelog/release-by-changelog@1.0.0
+
release-by-changelog:
- stage: release
- variables:
- CHANGELOG_FILEPATH: "docs/CHANGELOG.md"
+ variables:
+ TAG_PREFIX: "v"
+ NAME_PREFIX: "Version: "
```
-## Variables
+Available variables:
-You can customize the job by overriding the following variables:
-
-| 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` |
+| Name | Description | Default |
+| -------------------- | --------------------------------------------- | ----------- |
+| `CHANGELOG_FILEPATH` | The path to the `CHANGELOG.md` file. | from inputs |
+| `PREFIX` | Value to prepend to the tag and release name. | from inputs |
+| `SUFFIX` | Value to append to the tag and release name. | from inputs |
+| `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.
+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 and will be ignored by `release-by-changelog`.
Example:
@@ -82,14 +117,11 @@ Example:
#### 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.
+When the release is ready, the `Unreleased` title must be updated to the new version and date, following the following format: `## [{new_version}] - {now:%Y-%m-%d}`
-If you are using [bump_my_version](https://pypi.org/project/bump-my-version/), you can
-automate the update of the `Unreleased` section.
+##### Automation
-To do so, you need this configuration in your `.bumpversion.toml` or `pyproject.toml`
-file:
+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 `.bumpversion.toml` or `pyproject.toml` file:
```toml
[[tool.bumpversion.files]]
@@ -108,23 +140,20 @@ 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](.bumpversion.toml).
+You'll find a full example of the `bump_my_version` configuration [here](.bumpversion.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 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.
+* 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)
+
+## Notes
+
+Release by Changelog uses itself for its releases. This project is not related to the [CNRV](https://cnrv.info/) (yet).
diff --git a/templates/release-by-changelog.yml b/templates/release-by-changelog.yml
index 730bf5a6d0f50e1fc1a398f4249f4bf6c5fb9d08..1c40fa2f2b3f8baf14536b1b348ff3723aec93e1 100644
--- a/templates/release-by-changelog.yml
+++ b/templates/release-by-changelog.yml
@@ -1,67 +1,83 @@
+spec:
+ inputs:
+ stage:
+ description: The stage of the job.
+ default: deploy
+ changelog file path:
+ description: The path to the CHANGELOG.md file.
+ default: CHANGELOG.md
+ prefix:
+ description: Value to prepend to the tag and release name.
+ default: ''
+ suffix:
+ description: Value to append to the tag and release name.
+ default: ''
+
+---
release_by_changelog:
- variables:
- CHANGELOG_FILEPATH: CHANGELOG.md
- PREFIX: ''
- SUFFIX: ''
- TAG_PREFIX: $PREFIX
- TAG_SUFFIX: $SUFFIX
- NAME_PREFIX: $PREFIX
- NAME_SUFFIX: $SUFFIX
- image: registry.gitlab.com/gitlab-org/release-cli:v0.18.0
- stage: deploy
- script:
- # Use grep to find version headers and store them in a variable
- - 'headers=$(grep -nE "^## \[([0-9]+)\.([0-9]+)\.([0-9]+)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?\] - [0-9]{4}-[0-9]{2}-[0-9]{2}$" "$CHANGELOG_FILEPATH")'
+ variables:
+ CHANGELOG_FILEPATH: $[[ inputs.changelog file path ]]
+ PREFIX: $[[ inputs.prefix ]]
+ SUFFIX: $[[ inputs.suffix ]]
+ TAG_PREFIX: $PREFIX
+ TAG_SUFFIX: $SUFFIX
+ NAME_PREFIX: $PREFIX
+ NAME_SUFFIX: $SUFFIX
+ image: registry.gitlab.com/gitlab-org/release-cli:v0.18.0
+ stage: $[[ inputs.stage ]]
+ script:
+ # Use grep to find version headers and store them in a variable
+ - 'headers=$(grep -nE "^## \[([0-9]+)\.([0-9]+)\.([0-9]+)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?\] - [0-9]{4}-[0-9]{2}-[0-9]{2}$" "$CHANGELOG_FILEPATH")'
- # Extract first header line number
- - 'first_line=$(echo "$headers" | head -1 | cut -d: -f1)'
+ # Extract first header line number
+ - 'first_line=$(echo "$headers" | head -1 | cut -d: -f1)'
- # Check if we have a header, else exit
- - if [ -z "$first_line" ]; then
- - echo "No version headers found."
- - exit 1
- - fi
+ # Check if we have a header, else exit
+ - if [ -z "$first_line" ]; then
+ - echo "No version headers found."
+ - exit 1
+ - fi
- # Extract version and date from the first header
- - version=$(echo "$headers" | head -1 | grep -oE "\[([0-9]+)\.([0-9]+)\.([0-9]+)\]" | tr -d "[]")
- - date=$(echo "$headers" | head -1 | grep -oE "[0-9]{4}-[0-9]{2}-[0-9]{2}")
- # If date is different from today, format it
- - if [ "$date" != "$(date +%Y-%m-%d)" ]; then
- - formatted_date=$(date -u -d "$date" +"%Y-%m-%dT%H:%M:%SZ")
- - fi
+ # Extract version and date from the first header
+ - version=$(echo "$headers" | head -1 | grep -oE "\[([0-9]+)\.([0-9]+)\.([0-9]+)\]" | tr -d "[]")
+ - date=$(echo "$headers" | head -1 | grep -oE "[0-9]{4}-[0-9]{2}-[0-9]{2}")
+ # If date is different from today, format it
+ - if [ "$date" != "$(date +%Y-%m-%d)" ]; then
+ - formatted_date=$(date -u -d "$date" +"%Y-%m-%dT%H:%M:%SZ")
+ - fi
- # Extract second header line number for end of text range
- - 'second_line=$(echo "$headers" | sed -n "2p" | cut -d: -f1)'
+ # Extract second header line number for end of text range
+ - 'second_line=$(echo "$headers" | sed -n "2p" | cut -d: -f1)'
- # Determine end line
- - if [ -n "$second_line" ]; then
- - end_line=$((second_line - 1))
- - else
- # If there's no second header, use the end of the file
- - end_line=$(wc -l < "$CHANGELOG_FILEPATH")
- - fi
+ # Determine end line
+ - if [ -n "$second_line" ]; then
+ - end_line=$((second_line - 1))
+ - else
+ # If there's no second header, use the end of the file
+ - end_line=$(wc -l < "$CHANGELOG_FILEPATH")
+ - fi
- - start_line=$((first_line + 2))
- - if [ "$start_line" -le "$end_line" ]; then
- # Use sed to extract the text between the first and the potential second version header
- - text=$(sed -n "$start_line,$end_line p" "$CHANGELOG_FILEPATH")
- - echo "Text = $text"
- - else
- - echo "No text to extract, start line exceeds end line."
- - fi
+ - start_line=$((first_line + 2))
+ - if [ "$start_line" -le "$end_line" ]; then
+ # Use sed to extract the text between the first and the potential second version header
+ - text=$(sed -n "$start_line,$end_line p" "$CHANGELOG_FILEPATH")
+ - echo "Text = $text"
+ - else
+ - echo "No text to extract, start line exceeds end line."
+ - fi
- # Output the results
- - echo "Version = $version"
- - echo "Date = $date"
- - echo "Formatted Date = $formatted_date"
- - echo "Text:"
- - echo "$text"
+ # Output the results
+ - echo "Version = $version"
+ - echo "Date = $date"
+ - echo "Formatted Date = $formatted_date"
+ - echo "Text:"
+ - echo "$text"
- # Set the tag and name
- - tag="$TAG_PREFIX$version$TAG_SUFFIX"
- - name="$NAME_PREFIX$version$NAME_SUFFIX"
+ # Set the tag and name
+ - tag="$TAG_PREFIX$version$TAG_SUFFIX"
+ - name="$NAME_PREFIX$version$NAME_SUFFIX"
- # Create the release
- - release-cli create --name "$name" --tag-name "$tag" --description "$text" --released-at "$formatted_date"
- rules:
- - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+ # Create the release
+ - release-cli create --name "$name" --tag-name "$tag" --description "$text" --released-at "$formatted_date"
+ rules:
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH