gfsm 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c272fe1a10ec5d572c5730e7fae0c2576443887f970c38f1c1923d8195cf276a
-  data.tar.gz: 6c62f1a5cb113a2b0cfcbcf7415498a64311fb91354f76ce5402a0d267b112d6
+  metadata.gz: 1e82f5cdce1d37aced2b895cabbc7a9b24019ddfb0838a35b623ff097307c343
+  data.tar.gz: ef83dd15b50de4d9db1e28e92e354864379294f9f8485fd093682e59525afd7d
 SHA512:
-  metadata.gz: ac25726a4d7adb447f53ab68519de68ebc3b1691cb58ae6c5e216b6f81888806e27718ce46e8d209e3a874fd7b98a748c5cbc5162dd082299d4c20f4e2b5eb86
-  data.tar.gz: b304347cd26aa23411353499da1477e28c732b41f4164da0f1b20c9d6a224b8ce6bcc635691b041a3d9949254b175c10ac5ead6dfcfcef97b9d93176cbe9536d
+  metadata.gz: b2c98d7dce54ec8b5bed5a4a3f328b97778a95fb622d977af7051ad9c034e344fba153da0a495b5288ddf3498e2970b88a6e1b07c0760b67c9dd0da1974e758b
+  data.tar.gz: 67c36f148426d0f397fe076aae8bdcbe1cf94f17d8aef7098221bce59e2f864f63286ceabfa7bc34020c78718b5a96ab9f84ee4fc88e8e872fdc429fbfa2cc05

data/.gitlab-ci.yml

@@ -64,6 +64,13 @@ Publish gem:
     - if: "$GEM_HOST_API_KEY == null"
       when: never
     - if: "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH"
+      changes:
+        - bin/**/*
+        - lib/**/*
+        - Gemfile
+        - Gemfile.lock
+        - gfsm.gemspec
+        - .tools-versions
 
 Upload docker image:
   stage: docker
@@ -76,6 +83,14 @@ Upload docker image:
     - docker push --all-tags $CI_REGISTRY_IMAGE
   rules:
     - if: "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH"
+      changes:
+        - bin/**/*
+        - lib/**/*
+        - Gemfile
+        - Gemfile.lock
+        - gfsm.gemspec
+        - .tools-versions
+        - Dockerfile
 
 Create release:
   stage: release
@@ -94,3 +109,11 @@ Create release:
     - if: "$GEM_HOST_API_KEY == null"
       when: never
     - if: "$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH"
+      changes:
+        - bin/**/*
+        - lib/**/*
+        - Gemfile
+        - Gemfile.lock
+        - gfsm.gemspec
+        - .tools-versions
+        - Dockerfile

data/README.md

@@ -1,6 +1,6 @@
-# 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
@@ -13,36 +13,40 @@ 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
 
@@ -50,11 +54,13 @@ Once Ruby is present on your system you can install the dependencies by running
 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
 
@@ -68,33 +74,138 @@ Once that command completes, the gem will be available and you can invoke it fro
 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
-
-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
+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.
+
+### 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>
+```
+
+#### gfsm version
+
+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
 ```
 
-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
+Where:
 
-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.
+- `<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
+```

data/lib/commands/version.rb

@@ -32,7 +32,7 @@ module GFSM
           GFSM::Output.puts(version)
         when 'current'
           settings = GFSM::Tools::VersionBumperSettings.new(args)
-          version = GFSM::Tools::CurrentVersionLoader.load_current_version(settings.repository)
+          version = GFSM::Tools::CurrentVersionLoader.load_current_version(settings.repository, settings.initial_version)
 
           if settings.prerelease
             version.add_prerelease_suffix!(settings.prerelease_name)

data/lib/tools/current_version_loader.rb

@@ -6,10 +6,10 @@ require_relative '../data/version'
 module GFSM
   module Tools
     class CurrentVersionLoader
-      def self.load_current_version(repo)
+      def self.load_current_version(repo, initial_version)
         last_tag_name = GFSM::Tools::GitUtilities.extract_last_tag_name(repo)
 
-        return GFSM::Data::Version.new("0.0.0") unless last_tag_name
+        return GFSM::Data::Version.new(initial_version) unless last_tag_name
 
         if last_tag_name.downcase.start_with?("v") 
           last_tag_name.slice!(0)

data/lib/tools/version_bumper.rb

@@ -7,7 +7,7 @@ module GFSM
   module Tools
 
     class VersionBumperSettings
-      attr_reader :repository, :configuration, :force, :force_version, :prerelease, :prerelease_name, :from, :to
+      attr_reader :repository, :configuration, :force, :force_version, :prerelease, :prerelease_name, :from, :to, :initial_version
 
       def initialize(cli_args)
         @repository = GFSM::Tools::GitUtilities.load_repo(get_repository_path(cli_args))
@@ -18,6 +18,7 @@ module GFSM
         @prerelease_name = get_prerelease_name(cli_args)
         @from = get_from(cli_args)
         @to = get_to(cli_args)
+        @initial_version = get_initial_version(cli_args)
         @from = GFSM::Tools::GitUtilities.extract_last_tag_name(@repository) if @from.nil?
       end
 
@@ -32,6 +33,7 @@ module GFSM
           --to <hash, tag or HEAD>              # The commit hash or tag to stop at when extracting the commits. By default will use HEAD to get to the latest commit on the current branch
           --configuration <path>                # Path to the configuration YAML file
           --path <path>                         # Path to the repository. By default will use the current directory
+          --initial-version <x.y.z>             # Version to use when no existing version is found, useful when initializing the first one
         OPTIONS
 
         environment_variables = <<~ENVVARS
@@ -43,10 +45,11 @@ module GFSM
           REPOSITORY_PATH                       # Equivalent to --path
           FROM_COMMIT                           # Equivalent to --from
           TO_COMMIT                             # Equivalent to --to
+          INITIAL_VERSION                       # Equivalent to --initial-version
         ENVVARS
 
         return {
-          usage: "[--force] [--force-version <major|minor|patch>] [--configuration <configuration_file_path>] [--prerelease] [--prerelease-name <prerelease_name>] [--from <hash or tag>] [--to <hash, tag or HEAD>] [--path <repository_path]",
+          usage: "[--force] [--force-version <major|minor|patch>] [--configuration <configuration_file_path>] [--prerelease] [--prerelease-name <prerelease_name>] [--from <hash or tag>] [--to <hash, tag or HEAD>] [--path <repository_path] [--initial-version <x.y.z>]",
           options: options,
           environment_variables: environment_variables
         }
@@ -88,6 +91,10 @@ module GFSM
       def get_to(args)
         extract_switch_value(args, "--to", "HEAD", "TO_COMMIT")
       end
+      
+      def get_initial_version(args)
+        extract_switch_value(args, "--initial-version", "0.0.0", "INITIAL_VERSION")
+      end
     end
 
     class VersionBumper
@@ -100,7 +107,7 @@ module GFSM
       def execute
         changelog_commits = GFSM::Tools::GitUtilities.extract_commits_with_changelog_trailer(@settings.repository, @settings.from, @settings.to)
 
-        @version = GFSM::Tools::CurrentVersionLoader.load_current_version(@settings.repository)
+        @version = GFSM::Tools::CurrentVersionLoader.load_current_version(@settings.repository, @settings.initial_version)
         @subdivisions = GFSM::Tools::CommitsSubdivider.subdivide_commits(@settings.configuration, changelog_commits)
 
         if !@subdivisions || @subdivisions.empty?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gfsm
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Zille Marco
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-25 00:00:00.000000000 Z
+date: 2024-09-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yaml
@@ -65,7 +65,6 @@ files:
 - ".gitignore"
 - ".gitlab-ci.yml"
 - ".tool-versions"
-- ".version"
 - ".vscode/launch.json"
 - Dockerfile
 - Gemfile

data/.version

@@ -1 +0,0 @@
-0.5.1