Script to generate authors files by version for Bibtex

[scottrigby]

Automation script for #78

• For a given release, outputs the list of authors, committers, and co-authors from Git history
• Git is still the canonical source of truth for contributions. These files are needed only for academic reference (see Add a reference this content section  #78)
• If translations exist in a release, notes that the Principles and Glossary are authored in English, and outputs the list of translators per language
• I included an output file for our only non-pre-release tag so far, v1.0.0 (I'm assume we don't want to create Bibtex reference files for pre-releases. But if we ever do, this would work for those too) - preview v1.0.0 generated file 👀
• The script also allows "HEAD" as an argument to allow a preview of what the output will look like before each new release

Example usage:

Note that until our next planned release, the only full release v1.0.0 does not yet have translations, so we're also outputting HEAD for comparison:

mkdir -p reference
for VERSION in v1.0.0 HEAD; do
  ./scripts/authors-by-version.sh $VERSION > reference/authors-$VERSION.md
done

Example output:

Here's a git-like diff between the v1.0.0 and current HEAD files generated from the example command above:

Click to expand diff

--- reference/authors-v1.0.0.md	2024-08-10 23:53:34
+++ reference/authors-HEAD.md	2024-08-10 23:53:35
@@ -1,9 +1,14 @@
-# v1.0.0 Authors
+# HEAD Authors
 
 This file is generated from Git history of the other canonical files in this repo,
 and is purely a convenience for referencing in academic papers.
 See the full Git history of those files for additional context.
 
+## Language and Translations
+
+The GitOps Principles and Glossary are [authored](#authors-list) in English.
+See farther below for a list of [translators](#translators-list) by language.
+
 ## Authors List
 
 - Andrew Block <[email protected]>
@@ -37,6 +42,7 @@
 - Regina Scott <[email protected]>
 - Robert A Ficcaglia <[email protected]>
 - Roberth Strand <[email protected]>
+- Samuel Tauil <[email protected]>
 - Schlomo Schapiro <[email protected]>
 - Scott Rigby <[email protected]>
 - Sean Sundberg <[email protected]>
@@ -46,3 +52,29 @@
 - William Caban <[email protected]>
 - William Chia <[email protected]>
 - lloydchang <[email protected]>
+
+## Translators List
+
+### German
+
+- Bernd Stübinger <[email protected]>
+- Florian Heubeck <[email protected]>
+- Jan Knieling <[email protected]>
+- Jochen Bürkle <[email protected]>
+- Kevin Fritz <[email protected]>
+- Michael Rempel <[email protected]>
+- Richard Steinbrück <[email protected]>
+- Tung Beier <[email protected]>
+
+### Spanish
+
+- Diego Cristóbal Herreros <[email protected]>
+
+### Portuguese
+
+- João Paulo Vanzuita <[email protected]>
+- Samuel Tauil <[email protected]>
+
+### French
+
+- Francois LP <[email protected]>

Follow-up

• If we like this we can add to a GitHub Action (as of July 2024 GitHub added release types. We would want released to exclude pre-releases)
• It would be nice to auto-detect new translations - for now the markdown template is hard-coded with the list of languages, but it's very easy to manually add a new line for each new language. To automate that, we can auto detect the files, but we'd need a reasonable way to get the human-readable name for each language (currently they're listed in https://github.com/open-gitops/documents/blob/main/i18n/README.md but it's annoying to parse a markdown table. Also that file is hand-edited too, so not sure keeping this part manual here too is any worse)

[christianh814]

Added some thoughts, just some picking nits. It's good as is

[scottrigby]

Also ran through shellcheck and fixed a few things. Added one ignore because $files mysteriously (to me) doesn't work when quoted.