Contributing

Starting with GLAuth 2.4.0, we have reworked and optimized the build workflow, and this starts with a new contribution process.

Preparing to Commit

Format your code automatically using gofmt -d ./ before committing. If you forget this step, a subsequent pull request may fail.

Writing Commit Messages

Commit messages must be semantically correct; this is all conventions, of course, and the one that has worked well for us is Conventional Commits

Hereā€™s the minimum information you need to know:

A commit message contains a prefix, followed by a short explanation. It may also contain ā€œfooterā€ annotations, but these are not mandatory (albeit appreciated)

Should you bundle multiple items in the same commit (say a new feature and a bug fix), you canā€¦ wait no please donā€™t do that.

Commit Prefix

A prefix is written imperatively and looks like this:

1feat(plugins)!: Change the plugins API to allow NoSQL databases.

A quick decoding of this message reveals that this is a new feature (feat) and we optionally specify which area of GLAuth is impacted ((plugins)) - We also warn the reader of a breaking change (!)

A more innocuous change could be:

1chore: Add more comments in all modules.

Here is a pretty self-explanatory list of prefixes: feat, fix, chore, build, ci, perf, refactor, test, style

For instance:

1Reviewed-by: John Romero <john@romero.com>
2Tested-by: Joel Spolsky <joel@joelonsoftware.com>
3BREAKING-CHANGE: I am yelling because I broke the plugin API compatibility!

None of the people mentioned above were harmed in the writing of this example

Here is a far-from-exhaustive list of footer annotations:

Signed-Off-by, Acked-by, Reviewed-by, Helped-by, Co-authored by, Reported-by, Tested-by, Cc, Reference-to, See-also, BREAKING-CHANGE

Pull Requests

Creating a Pull Request

Create your Pull Requests from your branch directly to the ā€˜Masterā€™ branch. We discontinued use of the ā€˜Devā€™ branch as we wish to enforce pulling from tagged versions, as opposed to making the merge flow more difficult to follow by jumping through intermediate branches.

Merging a Pull Request

If you have the privileges to merge a pull request, please start by ensuring that it follows the proper conventions.

Note that pull requests that represent branch merges and other maintenance operations should not, in fact, follow these conventions. This allows us to exclude them from a releaseā€™s notes.

Releasing

Versioning

We follow the Semantic Version v2.0 conventions

Therefore, all releases follow this numbering scheme: v<major>.<minor>.<patch>, e.g. ā€˜v1.1.0ā€™

  • The patch number increments as we add bug fixed or minor tweaks
  • The minor number increments as we make significant changes, such as code refactoring
  • An increment of the major number denotes a breaking change!

You may submit an important feature that we all want to incorporate in GLAuth quickly. However, we cannot surprise our users by breaking their production setups. Therefore, we have to strike a balance between our desire to release the feature, and the need to wait for a major release to do so.

Creating a Release

We now rely on release-please to automate the creation of release notes based on semantically correct commits (see above)

Any commit message following the proper conventions will be included in the release notes, while ā€œhousekeepingā€ commits will not be.

To create a new release, in this example 2.0.0:

1git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"

The ā€˜release-pleaseā€™ action will create a Pull Request tracking all commits since the last release tag.

Copyright 2021