feat: add --version flag for external debugging (#27)

This contribution is part of the [FC-0012 project](https://openedx.atlassian.net/l/cp/XGS0iCcQ) which is sparked by the [Translation Infrastructure update OEP-58](https://open-edx-proposals.readthedocs.io/en/latest/architectural-decisions/oep-0058-arch-translations-management.html#specification).

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 name: Releases
 
-on: 
+on:
   push:
     tags:
     - '*'
@@ -12,6 +12,14 @@ jobs:
       contents: write
     steps:
     - uses: actions/checkout@v3
+    - name: set tag variable in atlas
+      run: |
+        # Sets _ATLAS_VERSION to the latest tag
+        CURRENT_TAG=$(git describe --exact-match --tags)
+        sed -i -e "s/_ATLAS_VERSION=.*/_ATLAS_VERSION=\"${CURRENT_TAG}\"  # Tagged by release.yml/" atlas
     - uses: ncipollo/release-action@v1
       with:
+        generateReleaseNotes: true  # GitHub generated notes are useful
+        allowUpdates: true  # GitHub UI makes hard to make a regular tag, therefore maintainers can create a release
+        artifactErrorsFailBuild: true  # Ensure that every release includes the `atlas` executable
         artifacts: "atlas"

README.rst

@@ -80,9 +80,11 @@ Releasing a New Version
 -----------------------
 This repository uses `semantic versioning <https://semver.org/>`_. To release a new version:
 
-* Cut a git tag with the new version number either via command-line e.g. ``git tag v1.0.0`` or the GitHub UI.
-* Wait for the ``release.yml`` GitHub Action to complete successfully, which uploads the latest ``atlas`` file to the release.
-* Edit the new release on GitHub to add release notes.
+* Create a GitHub release or a git tag via command line e.g. ``git tag v1.0.0``
+* Then, the ``release.yml`` GitHub Action will set the version number for ``atlas --version`` and creates a new release with ``atlas``.
+
+Note: The ``atlas --version`` command only outputs the version if it's downloaded from a GitHub release. Otherwise, it
+will output ``unreleased``.
 
 License
 -------

atlas

@@ -2,6 +2,10 @@
 # getoptions generates code that fails this check, so we need to disable it
 # shellcheck disable=SC2004
 
+# Atlas uses semantic versioning (https://semver.org/). To cut a new release, checkout the README:
+#    - https://github.com/openedx/openedx-atlas#releasing-a-new-version
+_ATLAS_VERSION="unreleased"  # release.yml GitHub Action will fill in the tag version
+
 # @getoptions
 parser_definition() {
     _ATLAS_USAGE_HELP="Atlas is a CLI tool that has essentially one command: \`atlas pull\`
@@ -78,6 +82,7 @@ More examples are available in the repository docs: https://github.com/openedx/o
 	msg 	 -- '' 'Commands:'
 	cmd pull -- "pull"
 	disp    :usage  -h --help
+	disp    _ATLAS_VERSION  --version
 }
 
 parser_definition_pull() {
@@ -114,6 +119,9 @@ parse() {
       '-h'|'--help')
         usage
         exit 0 ;;
+      '--version')
+        echo "${_ATLAS_VERSION}"
+        exit 0 ;;
       --)
         while [ $# -gt 0 ]; do
           REST="${REST} \"\${$(($OPTIND-$#))}\""
@@ -221,6 +229,7 @@ More examples are available in the repository docs: https://github.com/openedx/o
 Commands:
   pull      pull
   -h, --help                  
+      --version               
 GETOPTIONSHERE
 }
 # Generated by getoptions (END)

spec/version_spec.sh

@@ -0,0 +1,6 @@
+Describe 'Test the --version flag'
+  It 'Prints the version'
+    When run source ./atlas --version
+    The output should equal 'unreleased'
+  End
+End