A summary of the patterns and best practices I use in git commit messages.
The commits analyzed generally follow the well-established conventions documented in:
- How to Write a Git Commit Message by Chris Beams
- My favourite Git commit by David Thompson
These include using imperative mood in the subject line, separating subject from body with a blank line, wrapping at ~72 characters, and focusing the body on explaining why rather than what.
The sections below focus on patterns that expand or go beyond these standard recommendations, particularly for commits with extended messages (title + body).
When a commit involves undocumented conventions, non-obvious practices, or domain-specific knowledge, include that context in the message.
Example:
Add `pt-pt` alias for `pt` language flag
Since Brazilian Portuguese is the globally dominant variety of Portuguese
(in terms of number of speakers and cultural influence)
similar to how American English is for English,
it is common for people to use a `pt-pt` language code
to specifically refer to European Portuguese.
This commit therefore adds an alias `pt-pt` -> `pt`,
similar to the existing `en-gb` -> `en` alias for English (United Kingdom).
Despite the apparent redundancy, the `pt-pt` code is actually used in practice,
and indeed has an IETF language tag (`pt-PT`) and POSIX locale (`pt_PT`).
Rather than simply describing what changed, structure the body to walk the reader through the reasoning process that led to the change.
Example:
Currently the category pages (e.g. jobs/administrators/, jobs/editors/, etc.)
are having the title set to an empty string, `<title></title>`
because the `header.tpl` relies on `$seo_title` and falls back to `$html_title`.
The latter was not defined for category pages, and the former is being set
to the `title` field of the `categories` DB table, which is apparently empty.
By defining `$html_title`, the category pages should now have proper titles
(shown in browser tab/window titles), instead of defaulting to the page URL.
This structure helps future readers understand not just what was done, but why it was necessary and how the problem was diagnosed.
When a solution involves trade-offs or rejected alternatives, document them:
Example:
The simplest way to remove the build warnings and fix CI
would be to add explicit empty constructors with boilerplate javadoc,
but this would end up adding clutter the code without real value.
Another option would be to set `failOnWarnings` to false,
but this would make other, potentially more serious warnings,
potentially go unnoticed, which is undesirable in the long term.
Instead, this patch uses the `-missing` parameter to javadoc's doclint;
this will suppress all missing documentation warnings,
not just those of default constructors,
but it's all we can do since doclint doesn't provide fine-grained control.
This helps future maintainers understand why certain approaches weren't taken, preventing them from "rediscovering" rejected solutions.
When mentioning a pattern, concept or practice documented elsewhere, cite the source:
Example:
Wrap some long lines
This makes it easier to review changes, since diffs will be more localized.
See <https://rhodesmill.org/brandon/2012/one-sentence-per-line/> for context and motivation.
This both credits the source and provides a path for readers who want deeper understanding.
When describing context, link directly to the relevant code, if possible pointing directly to the relevant lines or range thereof:
Example:
The latter was not defined for category pages, and the former is being set
to the `title` field of the `categories` DB table, which is apparently empty
(as suggested by [db/jobberbase.sql](...blob/395ff0d8.../db/jobberbase.sql#L38-L66).
Use permalink URLs (with commit hashes or tag names) ensure the links remain valid even as the code evolves.
When a commit message requires multiple references to external resources (documentation, issues, commits, etc.), use footnotes to keep the prose readable while still providing comprehensive links.
Example:
Context:
- JavaDoc emits warnings about missing documentation [^1]
and since JDK v18 these also apply to default constructors [^2] [^3].
- Building this project results in such warnings
due to default constructors in all five mojos of this project,
which use implicit constructors (i.e. not present in source code).
- These build warnings then lead to CI failures,
due to the `failOnWarnings` option of maven-javadoc-plugin
being set to true in maven-tiles-plugins-javadoc [^4] [^5] [^6].
[... body continues ...]
[^1]: https://docs.oracle.com/en/java/javase/18/docs/specs/man/javadoc.html#doclint
[^2]: https://bugs.openjdk.org/browse/JDK-8249634
[^3]: https://github.com/openjdk/jdk/commit/c1c404896ca2791ad348a4cf482bec2c2ad98464
[^4]: https://gitlab.feedzai.com/.../pom.xml#L48
[^5]: https://gitlab.feedzai.com/.../tile.xml#L15
[^6]: https://gitlab.feedzai.com/.../tile.xml#L9
This approach separates the narrative from the reference machinery, making both easier to read.
When a commit builds on or relates to previous work (commits, issues, or PRs/MRs), reference it explicitly:
Example:
Further tweaks to pipe trick documentation (follow-up of Iaf365e31)
- call them pipe tricks (plural) as there's more than one
- mention double-width comma as well
- use one tab character for alignment due to double-width chars
- document reverse pipe trick
Or when reverting/restoring:
Restore title in text of 0BSD license (now present in SPDX)
This reverts commit bab9f14fa93405fead73948946c8ca9c2b62c1c5.
When wrapping lines, prefer to break at logical or semantic boundaries (e.g., after commas, conjunctions, or prepositions) rather than arbitrary line lengths, as described in the semantic linefeeds article.
Example:
This simplifies the logic in the code,
makes it more evident what the color means,
and avoids representing the same information in two different places.
This practice enhances readability of the commit message by reinforcing the semantic structure of the text, and helps identify overly long phrases at the time of writing.
fix(javadoc): suppress warnings for missing docs
Context:
- JavaDoc emits warnings about missing documentation [^1]
and since JDK v18 these also apply to default constructors [^2] [^3].
- Building this project results in such warnings
due to default constructors in all five mojos of this project,
which use implicit constructors (i.e. not present in source code).
- These build warnings then lead to CI failures,
due to the `failOnWarnings` option of maven-javadoc-plugin
being set to true in maven-tiles-plugins-javadoc [^4] [^5] [^6].
The simplest way to remove the build warnings and fix CI
would be to add explicit empty constructors with boilerplate javadoc,
but this would end up adding clutter the code without real value.
Another option would be to set `failOnWarnings` to false,
but this would allow other, potentially more serious warnings,
to go unnoticed, which is undesirable in the long term.
Instead, this patch uses the `-missing` parameter to javadoc's doclint [^1];
this will suppress all missing documentation warnings,
not just those of default constructors,
but it's all we can do since doclint doesn't provide fine-grained control
to suppress only default constructor warnings.
Note: We could alternatively use an external tool like `require-javadoc` [^7],
which doesn't require docstrings in default constructors [^8],
but that would require adding a new dependency,
and would not emit warnings about missing Javadoc tags
such as `@param` and `@return`.
[^1]: https://docs.oracle.com/en/java/javase/18/docs/specs/man/javadoc.html#doclint
[^2]: https://bugs.openjdk.org/browse/JDK-8249634
[^3]: https://github.com/openjdk/jdk/commit/c1c404896ca2791ad348a4cf482bec2c2ad98464
[^4]: https://gitlab.feedzai.com/commons/docusaurus-maven/-/blob/7cba6dc264fbe4ed1e166cebc33c6649176d5e94/pom.xml#L48
[^5]: https://gitlab.feedzai.com/commons/maven-tiles/-/blob/16.3.1/maven-tiles-facets/maven-tiles-facets-delivery/tile.xml#L15
[^6]: https://gitlab.feedzai.com/commons/maven-tiles/-/blob/16.3.1/maven-tiles-plugins/maven-tiles-plugins-javadoc/tile.xml#L9
[^7]: https://github.com/plume-lib/require-javadoc
[^8]: https://github.com/plume-lib/require-javadoc#comparison-to-javadoc--xwerror--xdoclintall
Add HTML titles for the category pages
Currently the category pages (e.g. [jobs/administrators/](https://www.fossjobs.net/jobs/administrators/),
[jobs/editors/](https://www.fossjobs.net/jobs/editors/), etc.)
are having the title set to an empty string, `<title></title>`
because the `header.tpl` relies on `$seo_title` and falls back to `$html_title`.
The latter was not defined for category pages, and the former is being set
to the `title` field of the `categories` DB table, which is apparently empty
(as suggested by [db/jobberbase.sql](https://github.com/fossjobs/fossjobs/blob/395ff0d8d7dbe562f3e66ec112cae3d67fa26cb5/db/jobberbase.sql#L38-L66).
By defining `$html_title`, the category pages should now have proper titles
(shown in browser tab/window titles), instead of defaulting to the page URL.
Add `pt-pt` alias for `pt` language flag
Since Brazilian Portuguese is the globally dominant variety of Portuguese
(in terms of number of speakers and cultural influence)
similar to how American English is for English,
it is common for people to use a `pt-pt` language code
to specifically refer to European Portuguese.
This commit therefore adds an alias `pt-pt` -> `pt`,
similar to the existing `en-gb` -> `en` alias for English (United Kingdom).
Despite the apparent redundancy, the `pt-pt` code is actually used in practice,
and indeed has an IETF language tag (`pt-PT`) and POSIX locale (`pt_PT`).
add hints on how to search wikidata pages
WikiBlame doesn't work for Wikidata item pages,
but there are many regular pages on Wikidata that can be searched with this tool.
I was not sure how to do it, though, and had to use trial and error until I succeeded.
In particular, the main hiccup was that if the user leaves the domain fields empty,
the first field defaults to 'en', and the second one to 'wikipedia'.
As a workaround, 'www' does work as a pseudo second-level domain for websites that don't really have one, like wikidata.org
Hopefully these hints will help others with similar searches :)
Add custom favicon to replace Jobberbase's default
Note: due to the simple geometry, the SVG favicon was written by hand,
to minimize the file size and maximize readability
(as much as the D attribute of SVG path elements allows, anyway.)
The shapes were drawn to align with a 16x16 grid.
The paths start at the top left corner of each letter,
and consist of horizontal and vertical line segments,
as well as and circular arcs for the J's curve.
A PNG version of the favicon is added as well, at 64x64px, for reference.
fix(redocusaurus): Omit the hostname in API endpoint paths via CSS
Some time ago the API documentation auto-generated by Redocusaurus
started including the documentation site's hostname in the API endpoint URLs
(not in the main endpoint heading, but in the dropdown box with selectable text for copying).
This was presumably avoidable by setting
[`hideHostname=true`](https://github.com/Redocly/redoc/blob/main/docs/config.md#hidehostname)
in the Redoc configuration options,
but this is [already the case](https://gitlab.feedzai.com/.../docusaurus.config.js#L161).
[It turns out](https://github.com/Redocly/redoc/issues/677#issuecomment-510806108)
that the OpenAPI definition itself states that a spec file needs to include a `host` field,
and when it doesn't, the engine rendering the HTML documentation
should use the hostname of the documentation site in its place.
Perhaps Redoc or Redocusaurus initially failed to adhere to this recommendation
and started doing so sometime ago,
or maybe the OpenAPI specs did include a `host` field and stopped doing so.
Either way, there's a workaround to address the issue,
which is to hide the hostname via CSS,
since it is helpfully wrapped in a `<span>` element of its own.
That is the approach used in this commit.
The CSS selector used to target the hostname span is not the most elegant,
since the element lacks an identifier or unique class, but it seems to work.