README.md in gfsm-0.5.1 vs README.md in gfsm-0.6.0

- old
+ new

@@ -1,8 +1,8 @@ -# GitLab Flavored Semantic Versionin +# GitLab Flavored Semantic Versioning -### Goal +## Goal This project tries to achieve automatic semantic versioning not basing the version bump on the conventional commits standars, but rather on a `Changelog` value on the trailer of commit messages. @@ -11,53 +11,59 @@ to get merged through a merge request. The beauty of this project is that you don't need to use the conventional commits specification, so you can have commits more similar to -``` +```plaintext Added new feature A to address this requirement ``` instead of -``` +```plaintext feat(<type>): added new feature A to address this requirement ``` This translates to: + - _**no "wasted" characters for that message prefix**_ - more readable commit messages - a nicer `Changelog` - ``` + + ```plaintext New features: - Added new feature A to address this requirement - Added feature B ``` + vs - ``` + + ```plaintext New features: - feat(<type>): added new feature A to address this requirement - feat: added feature B ``` -### Setup +## Setup The only tool you need to setup this project on your local environment is Ruby, which can be -downloaded using `asdf`. The Ruby version required is `2.7.5`. +downloaded using `asdf`. The Ruby version required is `3.2.4`. Once Ruby is present on your system you can install the dependencies by running ```shell bundle install ``` -### Testing +## Testing At the moment there's no built-in testing platform, but I'm planning to use `rspec` to add unit tests. -### Using +## Usage +### Installation + This project is available as a Ruby gem, so to be able to use it is enough to run ```shell gem install gfsm ``` @@ -66,35 +72,140 @@ ```shell gfsm help ``` -The main way this project can be used though, is inside a CI pipeline where you can invoke it to bump the version and/or update the changelog. +**Important**: `git` must be avaiable on the system for the gem to work. -In order to use is inside a CI job, the job itself could look something like this: +The main way this project can be used though, is inside a CI pipeline where you can invoke it to bump +the version and/or update the changelog. -```yaml -stages: - - version +To facilitate this, a docker image is published with every release of this tool. +[Here](https://gitlab.com/zille_marco/gitlab-flavored-semantic-versioning/container_registry/3294324) +is a list of all the available images. -update-version: - stage: version - image: ruby:3.2.4 - before_script: - - gem install gfsm - script: - - gfsm version bump --force > .version - - gfsm changelog --force --output-file CHANGELOG.md - - echo "RELEASE_VERSION=$(<.version)" >> variables.env - artifacts: - reports: - dotenv: variables.env - paths: - - .version - - CHANGELOG.md +### Available commands + +The main commands available are: + +- `gfsm version`: this command takes care of the project's verioning. +- `gfsm changelog`: this command takes care of the project's changelog. +- `gfsm help`: this command will display the available commands and their usage. + +To use these commands, you can invoke the `gfsm` executable from the command line. For example: + +```shell +gfsm version <subcommand> +gfsm changelog <subcommand> ``` -With this, subsequent jobs that depend on the `update-version` job will: -- be able to get the new version form the `RELEASE_VERSION` environment variable -- read the `CHANGELOG.md` file to get an updated changelog file +#### gfsm version -To have a working example of the things described above you can have a look at the `.gitlab-ci.yml` of this project, which implements this exact concept. \ No newline at end of file +The `version` command has its own subcommands: + +- `bump`: used to bump the version to the next one +- `current`: used to extract the current version +- `help`: used to print the usage of the `vesion` command itself + +All subcommands are configurable through either CLI flags or environment variables, that have precedence +over the CLI flags. + +| CLI flag | Environment variable | Accepted values | Default | Description | +| ------------------- | -------------------- | ------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `--force` | `FORCE_BUMP` | | | If there are no commits with a changelog trailer, the version will still be bumped. | +| `--force-version` | `FORCE_BUMP_VERSION` | `major`, `minor`, `patch` | `patch` | If the version needs to be force-bumped, this flag instructs the tool which section of the version to bump. | +| `--prerelease` | `PRERELEASE` | | | Turns on prerelease generation, which by default appends `-pre` to the generated version. | +| `--prerelease-name` | `PRERELEASE_NAME` | Any string without whitespaces | `pre` | When prerelease generation is enabled, this overrides the default `pre` value appended as suffix to the generated version. | +| `--configuration` | `CONFIGURATION_FILE` | A file path | `./gfsmrc.yml` | The path to the YAML configuration file. | +| `--path` | `REPOSITORY_PATH` | A folder path | `.` | The path to the folder containing the Git repository. | +| `--from` | `FROM_COMMIT` | A commit SHA or a tag name | The latest **reachable** tag | The commit SHA or the tag name from where to start scraping for commit messages. | +| `--to` | `TO_COMMIT` | A commit SHA or a tag name | `HEAD` | The commit SHA or the tag name where to stop scraping for commit messages. | +| `--initial-version` | `INITIAL_VERSION` | A semantic version value | `0.0.0` | The version used when the project doesn't have one yet, useful for the first initialization of the project. | + +#### gfsm changelog + +The `changelog` command has its own subcommands: + +- `generate`: used to generate a changelog for the latest version +- `extract`: used to extract a section from the changelog associated with a specific version +- `help`: used to print the usage of the `changelog` command itself + +All subcommands are configurable through either CLI flags or environment variables, that have precedence +over the CLI flags. + +The `changelog` command supports all the flags and environment variables of the `version` command, with +the following additions. + +| CLI flag | Environment variable | Accepted values | Default | Description | +| -------------------- | -------------------- | --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--output-file` | `OUTPUT_FILE` | A file path | | The path to the CHANGELOG.md file, which will be created if not existing. If not specified the changelog will be written to stdout. **Only usable with `generate`**. | +| `--input-file` | `INPUT_FILE` | A file path | `./CHANGELOG.md` | The path to the CHANGELOG.md file. **Only usable with `extract`**. | +| `--no-incremental` | `NO_INCREMENTAL` | | | When provided, the output file will always be overridden and will contain only the changelog entries for the latest version. | +| `--only-new-entries` | `ONLY_NEW_ENTRIES` | | | When provided, the output will always be written to stdout and will only contain the changelog for the latest changes without the version header. | +| `--extract-version` | `EXTRACT_VERSION` | A version name | | When provided, this specifies the version that `extract` will extract the release notes from. If not provided, or set to `latest`, it will extract the release notes from the latest version. | + +### Configuration + +GFSM can be cofigured by providing a YAML configuration file which will contain informations about the +supported changelog trailers, the section they belong to and their priority. + +The schema is the following: + +```plaintext +change_types: + <identifier>: + title: string + matcher: string + bump: major|minor|patch + priority: number +``` + +Where: + +- `<identifier>` is used only to separate the different sections +- `title` is the title used when generating the changelog +- `matcher` is the string that the commit changelog trailer has to contain in order to match the section +- `bump` tells the tool which section of the version to bump when a commit changelog trailer matches + the section +- `priority` is used to order the sections when generating the changelog, the higher the priority the + higher up the section will be in the changelog + +Here is an example: + +```yaml +change_types: + new_features: + title: "New features" + matcher: added + bump: minor + priority: 6 + feature_removals: + title: "Feature removals" + matcher: removed + bump: major + priority: 5 + deprecations: + title: "Deprecations" + matcher: deprecated + bump: minor + priority: 4 + feature_changes: + title: "Feature changes" + matcher: changed + bump: minor + priority: 3 + fixes: + title: "Fixes" + matcher: fixed + bump: patch + priority: 2 + security_fixes: + title: "Security fixes" + matcher: security + bump: patch + priority: 1 + other: + title: "Other" + matcher: other + bump: patch + priority: 0 +```