Automate template setup process via CI for GitHub users (#143)

* Technical improvement
* Minor change
* Impacted areas: Setup script and CI workflows
* Details:
  - Automate template setup process via CI for GitHub users:
    - When creating a new repository by using this template on GitHub, the setup script is automatically executed by the CI on the resulting generated repository.
  - Improve accessibility by adopting less technical terminology:
    - Replace "bootstrap" with "first-time setup", clarifying its purpose as a one-time project initialisation, particularly for users unfamiliar with the technical vocabulary.
  - Decompose GitHub Actions monolithic workflow into specialized workflows:
    - Split the `Country-Template` workflow into three distinct workflows: `build`, `validate` and `deploy`.
  - Enhance accuracy of workflow triggers:
    - Trigger deployment only when changes are pushed to the `main` branch.
    - Trigger validation on PR events or as a dependency of the deployment workflow.
  - Update CI dependencies
    
- - - -

These changes:

- Change non-functional parts of this repository: CI, setup script and
documentation

The automation of template setup process via CI can be tested on my fork
[here](https://github.com/new?template_name=country-template&template_owner=Ndpnt)

.github/workflows/build.yml

@@ -0,0 +1,34 @@
+name: Build
+
+on:
+  workflow_call:
+
+jobs:
+  build-and-cache:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9.12 # Patch version must be specified to avoid any cache confusion, since the cache key depends on the full Python version. Any difference in patches between jobs will lead to a cache not found error.
+
+      - name: Cache build
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }} # Cache the entire build Python environment
+          restore-keys: |
+            build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}
+            build-${{ env.pythonLocation }}-
+      
+      - name: Build package
+        run: make build
+
+      - name: Cache release
+        uses: actions/cache@v4
+        with:
+          path: dist
+          key: release-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}

.github/workflows/deploy.yml

@@ -0,0 +1,51 @@
+name: Deploy
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  validate:
+    uses: "./.github/workflows/validate.yml"
+
+  # GitHub Actions does not have a halt job option to stop from deploying if no functional changes were found.
+  # We thus execute a separate deployment job depending on the output of this job.
+  check-for-functional-changes:
+    runs-on: ubuntu-22.04
+    outputs:
+      status: ${{ steps.stop-early.outputs.status }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all the tags
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9.12
+      - id: stop-early
+        run: if "${GITHUB_WORKSPACE}/.github/has-functional-changes.sh" ; then echo "::set-output name=status::success" ; fi
+
+  deploy:
+    runs-on: ubuntu-22.04
+    needs: [ validate, check-for-functional-changes ]
+    if: needs.check-for-functional-changes.outputs.status == 'success'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9.12
+      - name: Restore build
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}
+      - name: Restore built package
+        uses: actions/cache@v4
+        with:
+          path: dist
+          key: release-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}
+      - name: Upload a Python package to PyPi
+        run: twine upload dist/* --username __token__ --password ${{ secrets.PYPI_TOKEN_OPENFISCA_BOT }}
+      - name: Publish a git tag
+        run: "${GITHUB_WORKSPACE}/.github/publish-git-tag.sh"

.github/workflows/first-time-setup.yml

@@ -0,0 +1,36 @@
+name: First time setup
+
+on:
+  create:
+  workflow_dispatch:
+
+permissions: 
+  actions: write
+  checks: write
+  contents: write
+
+jobs:
+  first-time-setup:
+    # Ensure this job does not run on the template repository or when the repository is forked
+    if: ${{ !github.event.repository.is_template && !github.event.repository.fork }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Infer jurisdiction name from repository name
+        run: |
+          echo "TITLE_CASE_JURISDICTION_NAME=$(echo ${{ github.event.repository.name }} | sed 's/openfisca-//' | sed 's/[-|_]/ /g' | awk '{for (i=1; i<=NF; i++) $i=toupper(substr($i,1,1)) substr($i,2)} 1')" >> $GITHUB_ENV
+
+      - name: Execute the first-time-setup script
+        run: CI=true JURISDICTION_NAME="$TITLE_CASE_JURISDICTION_NAME" REPOSITORY_URL="${{ github.repositoryUrl }}" ./first-time-setup.sh
+
+      - name: Commit changes
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "Customise country-template through CI"
+          tagging_message: "0.0.1"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/validate.yml

@@ -0,0 +1,93 @@
+name: Validate
+
+on:
+  pull_request:
+    types: [ assigned, opened, reopened, synchronize, ready_for_review ]
+  workflow_call:
+
+jobs:
+  build:
+    uses: "./.github/workflows/build.yml"
+
+  lint-files:
+    runs-on: ubuntu-22.04
+    needs: [ build ]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all the tags
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9.12
+
+      - name: Restore build
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}
+
+      - run: make check-syntax-errors
+
+      - run: make check-style
+
+      - name: Lint Python files
+        run: "${GITHUB_WORKSPACE}/.github/lint-changed-python-files.sh"
+
+      - name: Lint YAML tests
+        run: "${GITHUB_WORKSPACE}/.github/lint-changed-yaml-tests.sh"
+
+  test-yaml:
+    runs-on: ubuntu-22.04
+    needs: [ build ]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9.12
+
+      - name: Restore build
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}
+
+      - run: make test
+
+  test-api:
+    runs-on: ubuntu-22.04
+    needs: [ build ]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9.12
+
+      - name: Restore build
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.pythonLocation }}
+          key: build-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-${{ github.sha }}
+
+      - name: Test the Web API
+        run: "${GITHUB_WORKSPACE}/.github/test-api.sh"
+
+  check-version-and-changelog:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all the tags
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.9.12
+
+      - name: Check version number has been properly updated
+        run: "${GITHUB_WORKSPACE}/.github/is-version-number-acceptable.sh"