Introducing new commit conventions in system roles

[Sergei Petrosian]

Hello team,

We introduce commit conventions in our organizations that will help us
automate many release tasks - automatically collect commits into changelog,
determine semantic version of new releases, and collect commits into
release notes.

We will follow Conventional Commits
<https://www.conventionalcommits.org/en/v1.0.0/> format, it requires you to
provide commit type and optional `!` after the commit type to indicate that
your commit introduces a breaking API change. You can find more information
at Conventional
<https://linux-system-roles.github.io/contribute.html#conventional-commits...
Commits format
<https://linux-system-roles.github.io/contribute.html#conventional-commits...
section on our site. It also generally improves commits hygiene in our org.

A correct commit format will be verified by a CommitLint GitHub Action, it
will verify each commit in the PR to follow conventional commits format,
and also the PR title to follow the format for consistency. The action
won't be able to verify if we provide a correct commit type and if we
indicate a breaking change correctly, so we must pay special attention to
it.

One concern is with the *Squash and merge *strategy that PRs currently use.
When you click the *Squash and merge* button in GitHub UI, it lets you
manually modify the resulting commit and push it to main right away. This
is a subject to human error because the resulting commit goes straight to
main, and in the case of a typo we would need to force push to main to fix
it. It is best to move to a *Rebase and merge *strategy instead to ensure
that all commits pushed to main have passed CommitLint checks. This is not
ideal but the pay off is huge.

Let me know if you have any concerns or questions.

Thank you

-- 

Sergei Petrosian, RHCE

He / Him / His

Software Engineer, RHEL System Roles

Red Hat Prague, Czech Republic <https://www.redhat.com>

spetrosi(a)redhat.com
M: [phone]     IRC: spetrosi
<https://www.redhat.com>

[Sergei Petrosian]

I am returning the *Squash and merge* option for PRs. Still, GitHub web UI
requests you to manually modify the resulting commit, ensure that you write
a meaningful commit message because it will appear in changelog and release
notes.

Now, commitlint verifies commits prior to adding them to changelog, this
helps to avoid possible errors.

Thank you

On Thu, Apr 20, 2023 at 8:58 AM Sergei Petrosian <spetrosi(a)redhat.com&gt;
wrote:

>  Hello team,
>
>  We introduce commit conventions in our organizations that will help us
>  automate many release tasks - automatically collect commits into changelog,
>  determine semantic version of new releases, and collect commits into
>  release notes.
>
>  We will follow Conventional Commits
>  <https://www.conventionalcommits.org/en/v1.0.0/> format, it requires you
>  to provide commit type and optional `!` after the commit type to indicate
>  that your commit introduces a breaking API change. You can find more
>  information at Conventional
>  <https://linux-system-roles.github.io/contribute.html#conventional-commits...
>  Commits format
>  <https://linux-system-roles.github.io/contribute.html#conventional-commits...
>  section on our site. It also generally improves commits hygiene in our org.
>
>  A correct commit format will be verified by a CommitLint GitHub Action, it
>  will verify each commit in the PR to follow conventional commits format,
>  and also the PR title to follow the format for consistency. The action
>  won't be able to verify if we provide a correct commit type and if we
>  indicate a breaking change correctly, so we must pay special attention to
>  it.
>
>  One concern is with the *Squash and merge *strategy that PRs currently
>  use. When you click the *Squash and merge* button in GitHub UI, it lets
>  you manually modify the resulting commit and push it to main right away.
>  This is a subject to human error because the resulting commit goes straight
>  to main, and in the case of a typo we would need to force push to main to
>  fix it. It is best to move to a *Rebase and merge *strategy instead to
>  ensure that all commits pushed to main have passed CommitLint checks. This
>  is not ideal but the pay off is huge.
>
>  Let me know if you have any concerns or questions.
>
>  Thank you
>
>  --
>
>  Sergei Petrosian, RHCE
>
>  He / Him / His
>
>  Software Engineer, RHEL System Roles
>
>  Red Hat Prague, Czech Republic <https://www.redhat.com>
>
>  spetrosi(a)redhat.com
>  M: [phone]     IRC: spetrosi
>  <https://www.redhat.com>
>  

-- 

Sergei Petrosian, RHCE

He / Him / His

Software Engineer, RHEL System Roles

Red Hat Prague, Czech Republic <https://www.redhat.com>

spetrosi(a)redhat.com
M: [phone]     IRC: spetrosi
<https://www.redhat.com>

[Sergei Petrosian]

Hi team,

it's me again, I an sorry for a lot of noise on this subject, turned out
that how I planned it initially does not work so good, so I am applying
more changes.

The previous approach of collection each commit to the changelog has a big
drawback - developers write commit messages for other developers, not for
end users. The commit must state clearly why the code was changed, and
because of it, often commit messages include information that end users do
not care about.

So, it makes more sense to keep commit messages for developers, and move
the user-aimed information in PR description and title.

I am reverting the commitlint check on commits, commitlint will now only
check PR titles to comply with the format. And commit messages do not
require any formatting.

Some more information on this can be found in the updated contribute guide:

https://linux-system-roles.github.io/contribute.html#write-a-good-pr-titl...

Let me know if you have any questions or concerns.

Thank you

On Fri, May 26, 2023 at 11:02 AM Sergei Petrosian <spetrosi(a)redhat.com&gt;
wrote:

>  I am returning the *Squash and merge* option for PRs. Still, GitHub
> web
>  UI requests you to manually modify the resulting commit, ensure that you
>  write a meaningful commit message because it will appear in changelog and
>  release notes.
>
>  Now, commitlint verifies commits prior to adding them to changelog, this
>  helps to avoid possible errors.
>
>  Thank you
>
>  On Thu, Apr 20, 2023 at 8:58 AM Sergei Petrosian <spetrosi(a)redhat.com&gt;
>  wrote:
>
> > Hello team,
> >
> > We introduce commit conventions in our organizations that will help us
> > automate many release tasks - automatically collect commits into changelog,
> > determine semantic version of new releases, and collect commits into
> > release notes.
> >
> > We will follow Conventional Commits
> > <https://www.conventionalcommits.org/en/v1.0.0/> format, it requires you
> > to provide commit type and optional `!` after the commit type to indicate
> > that your commit introduces a breaking API change. You can find more
> > information at Conventional
> >
> <https://linux-system-roles.github.io/contribute.html#conventional-commits...
> > Commits format
> >
> <https://linux-system-roles.github.io/contribute.html#conventional-commits...
> > section on our site. It also generally improves commits hygiene in our org.
> >
> > A correct commit format will be verified by a CommitLint GitHub Action,
> > it will verify each commit in the PR to follow conventional commits format,
> > and also the PR title to follow the format for consistency. The action
> > won't be able to verify if we provide a correct commit type and if we
> > indicate a breaking change correctly, so we must pay special attention to
> > it.
> >
> > One concern is with the *Squash and merge *strategy that PRs currently
> > use. When you click the *Squash and merge* button in GitHub UI, it lets
> > you manually modify the resulting commit and push it to main right away.
> > This is a subject to human error because the resulting commit goes straight
> > to main, and in the case of a typo we would need to force push to main to
> > fix it. It is best to move to a *Rebase and merge *strategy instead to
> > ensure that all commits pushed to main have passed CommitLint checks. This
> > is not ideal but the pay off is huge.
> >
> > Let me know if you have any concerns or questions.
> >
> > Thank you
> >
> > --
> >
> > Sergei Petrosian, RHCE
> >
> > He / Him / His
> >
> > Software Engineer, RHEL System Roles
> >
> > Red Hat Prague, Czech Republic <https://www.redhat.com>
> >
> > spetrosi(a)redhat.com
> > M: [phone]     IRC: spetrosi
> > <https://www.redhat.com>
> >
>
>
>  --
>
>  Sergei Petrosian, RHCE
>
>  He / Him / His
>
>  Software Engineer, RHEL System Roles
>
>  Red Hat Prague, Czech Republic <https://www.redhat.com>
>
>  spetrosi(a)redhat.com
>  M: [phone]     IRC: spetrosi
>  <https://www.redhat.com>
>  

-- 

Sergei Petrosian, RHCE

He / Him / His

Software Engineer, RHEL System Roles

Red Hat Prague, Czech Republic <https://www.redhat.com>

spetrosi(a)redhat.com
M: [phone]     IRC: spetrosi
<https://www.redhat.com>