Adopt conventional commits (PR title only) and Semantic Release for enhanced release management

[swade1987]

Objective: To improve our project's release management process, enhance the clarity of pull request titles, and streamline the generation of changelogs, I propose the adoption of the Conventional Commits specification for all pull request titles combined with the integration of Semantic Release Action for automated version management and release description organization.

Background: Our current process for versioning and generating release notes requires significant manual effort, needs more consistency, and can lead to errors or omissions in our changelogs. This proposal addresses these issues by implementing a structured, automated approach.

Proposal Details:

1. Adopt Conventional Commits: Following the Conventional Commits specification for our pull request titles, we introduce a standardised format that communicates the nature of changes in each pull. This format supports semantic versioning and facilitates automated tooling.
2. Implement Semantic Release Action: Utilizing the Semantic Release Action on GitHub, we can automate the versioning and release process based on the commit messages. This tool automatically generates version numbers, releases, and changelogs by analyzing commits since the last release.

Benefits:

1. Automated Changelog Generation: As seen in the Terraform AWS EKS module's changelog, Semantic Release Action automatically creates detailed, organized changelogs, saving time and reducing human error.
2. Structured Release Descriptions: Release descriptions are automatically segmented into necessary sections (features, bug fixes, etc.), improving readability and accessibility for users. The releases page of the Terraform AWS EKS module showcases this structured approach.
3. Consistency and Clarity: Conventional Commits ensure consistent pull request titles, making it easier to understand the project history and the impact of each change.
4. Efficiency: Reducing manual efforts in version management and changelog generation allows the team to focus on development and reduce the time to release.

Implementation Considerations:

1. Training and Documentation: We must provide guidelines to adapt to the Conventional Commits specification.
2. Integration and Workflow Adjustment: Implementing Semantic Release Action will require our CI/CD pipeline adjustments to integrate the automated versioning and release processes.

Conclusion: Adopting Conventional Commits and Semantic Release Action represents a strategic move to enhance our project's release management. It offers a more efficient, clear, and automated versioning and changelog generation approach. We can significantly improve our release process's effectiveness and reliability by following best practices demonstrated by successful projects like the Terraform AWS EKS module.

I welcome feedback, questions, and suggestions on this proposal.

[swade1987]

We can use the following GH action to ensure Pull Request titles use the semantic commit structure.

name: semantic-lint

on:
  pull_request_target:
    types:
      - opened
      - edited
      - synchronize

permissions:
  contents: read
  pull-requests: read

jobs:
  lint:
    name: semantic-lint
    runs-on: ubuntu-latest
    steps:
      - uses: amannn/action-semantic-pull-request@v5
        env:
          GITHUB_TOKEN: ${{ secrets.XXX }}

[kingdonb]

Am I to understand this includes an institution of commit message standards, in order to facilitate the automatic changelog generation?

Training and Documentation: We must provide guidelines to adapt to the Conventional Commits specification.

I guess that's what you meant here...

https://www.conventionalcommits.org/en/v1.0.0/#summary

So all commits would have to conform to this standard? I'm not saying I am not for this, in general I prefer to implement the release processes that result in an automatic generated changelog. I am for it, but this needs to be communicated well, as it is not the standard currently across any of the other Flux project repos.

I will try the semantic-lint action in one of my repos 👍

[swade1987]

@kingdonb, we would only enforce this on the PR title, not the individual commits. We only need to do this because we are squashing all commits anyway.

[stefanprodan]

We are not squashing commits, this would be awful as squashing in GH removes the pgp signatures.

For this repo it may make sense to not write changelogs as it’s very low traffic, but IMO for all other Flux components the changelog should be written by humans for humans, no user will read hundreds of PR descriptions to understand what are we shipping.