Update cookiecutter to new standard via cruft (#319)

### What kind of change does this PR introduce?

* Updates the cookiecutter with the newest conventions and workflows

### Does this PR introduce a breaking change?

Boilerplate documentation is largely unchanged. Workflows are now more a
bit more elegant, including automatic labelling, warnings about unsafe
changes to workflows, security-related changes, etc.

`actions-versions-updater.yml` has been replaced with `Dependabot` (it's
just better).

There's support for evaluating the OpenSSF Scorecard (this can be
disabled if we want).

Code formatting tools are now hard-pinned. These need to be kept in sync
with changes from `pre-commit`. `Dependabot` should do this task
automatically via Pull Requests.

Versioning scheme is now SemVer 2.0-compliant:
* If the version doesn't end in `-dev` or `-dev.##`, `$ bump-my-version
bump patch` will be called. This will set the version at `X.Y.Z+1-dev`.
Otherwise, `$ bump-my-version bump build` will be called. This is all
automated by the `bump-version.yml`.

When the version is ready for a release, it's up to the maintainer to
call the following:
* `$ bump-my-version bump release` (for a patch release; i.e. `1.2.0` →
`1.2.1`) or
* `$ bump-my-version bump minor` then `$ bump-my-version bump release`
(for a minor release; i.e. `1.2.0` → `1.3.0`)

There is now also support for Documentation locales (translations) via
`.po` files. These can be staged with `$ make initialize-translations`,
whereby `.po` files will be generated and French (or other) language
strings can be added.
* **I'm not sure how this will interact with existing translation code.
Might be worth it to leave this deactivated**

### Other information:

Ouranosinc/cookiecutter-pypackage#30

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "/home/tjs/git/cookiecutter-pypackage",
-  "commit": "64eceda7d95aeb8937fa9961989d3d617a525c04",
+  "commit": "55001f0fb2b470d1be2e992bfb8e006b4bc3807c",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -11,12 +11,13 @@
       "project_slug": "xscen",
       "project_short_description": "A climate change scenario-building analysis framework, built with xclim/xarray.",
       "pypi_username": "RondeauG",
-      "version": "0.8.2-beta",
+      "version": "0.8.2",
       "use_pytest": "y",
       "use_black": "y",
       "use_conda": "y",
       "add_pyup_badge": "n",
       "make_docs": "y",
+      "add_translations": "y",
       "command_line_interface": "Click",
       "create_author_file": "y",
       "open_source_license": "Not open source",

.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: daily
+      time: '12:00'
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: daily
+      time: '12:00'
+    open-pull-requests-limit: 10

.github/labeler.yml

@@ -36,4 +36,4 @@
 'xclim':
   - changed_files:
     - any-glob-to-any-file:
-      - 'scen/xclim_modules/**/*'
+      - 'xscen/xclim_modules/**/*'

.github/workflows/bump-version.yml

@@ -1,3 +1,8 @@
+# This workflow requires a personal access token named `BUMP_VERSION_TOKEN` with the following privileges:
+# - Contents: Read and Write
+# - Metadata: Read-Only
+# - Pull Requests: Read and Write
+
 name: "Bump Patch Version"
 
 on:
@@ -27,7 +32,6 @@ on:
       - environment-dev.yml
       - environment.yml
       - pyproject.toml
-      - setup.cfg
       - setup.py
       - templates
       - tests/*.py
@@ -64,14 +68,23 @@ jobs:
         run: |
           git config --local user.email "bumpversion[bot]@ouranos.ca"
           git config --local user.name "bumpversion[bot]"
+      - name: Install bump-my-version
+        run: |
+          python -m pip install "bump-my-version>=0.17.1"
       - name: Current Version
-        run: echo "current_version=$(grep -E '__version__'  xscen/__init__.py | cut -d ' ' -f3)"
-      - name: Bump Patch Version
         run: |
-          python -m pip install bump-my-version
-          echo "Bumping version"
-          bump-my-version bump --tag patch
-          echo "new_version=$(grep -E '__version__'  xscen/__init__.py | cut -d ' ' -f3)"
+          bump-my-version show current_version
+          CURRENT_VERSION="$(grep -E '__version__'  xscen/__init__.py | cut -d ' ' -f3)"
+          echo "CURRENT_VERSION=${CURRENT_VERSION}" >> $GITHUB_ENV
+      - name: Conditional Bump Version
+        run: |
+          if [[ ${{ env.CURRENT_VERSION }} =~ -dev(\.\d+)? ]]; then
+            echo "Development version (ends in 'dev(\.\d+)?'), bumping 'build' version"
+            bump-my-version show new_version --increment build
+          else
+            echo "Version is stable, bumping 'patch' version"
+            bump-my-version show new_version --increment patch
+          fi
       - name: Push Changes
         uses: ad-m/github-push-action@v0.8.0
         with:

.github/workflows/cache-cleaner.yml

@@ -0,0 +1,47 @@
+# Example taken from https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#managing-caches
+name: Cleanup Caches on Pull Request Merge
+on:
+  pull_request:
+    types:
+      - closed
+
+permissions:  # added using https://github.com/step-security/secure-repo
+  contents: read
+
+jobs:
+  cleanup:
+    name: Cleanup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            api.github.com:443
+            github.com:443
+            objects.githubusercontent.com:443
+
+      - uses: actions/checkout@v4.1.1
+
+      - name: Cleanup
+        run: |
+          gh extension install actions/gh-actions-cache
+
+          REPO=${{ github.repository }}
+          BRANCH="refs/pull/${{ github.event.pull_request.number }}/merge"
+
+          echo "Fetching list of cache key"
+          cacheKeysForPR=$(gh actions-cache list -R $REPO -B $BRANCH -L 100 | cut -f 1 )
+
+          ## Setting this to not fail the workflow while deleting cache keys.
+          set +e
+          echo "Deleting caches..."
+          for cacheKey in $cacheKeysForPR
+          do
+              gh actions-cache delete $cacheKey -R $REPO -B $BRANCH --confirm
+          done
+          echo "Done"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/dependency-review.yml

@@ -0,0 +1,31 @@
+# Dependency Review Action
+#
+# This Action will scan dependency manifest files that change as part of a Pull Request, surfacing known-vulnerable versions of the packages declared or updated in the PR. Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable packages will be blocked from merging.
+#
+# Source repository: https://github.com/actions/dependency-review-action
+# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
+name: 'Dependency Review'
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            api.github.com:443
+            github.com:443
+
+      - name: 'Checkout Repository'
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+      - name: 'Dependency Review'
+        uses: actions/dependency-review-action@4901385134134e04cec5fbe5ddfe3b2c5bd5d976

.github/workflows/first_pull_request.yml → .github/workflows/first-pull-request.yml

@@ -53,7 +53,7 @@ jobs:
               repo: context.repo.repo,
               body: `**Welcome**, new contributor!
 
-              It appears that this is your first Pull Request. To give credit where it's due, we ask that you add your information to the \`AUTHORS.rst\` and \`.zenodo.json\`.:
+              It appears that this is your first Pull Request. To give credit where it's due, we ask that you add your information to the \`AUTHORS.rst\` and \`.zenodo.json\`:
                - [ ] The relevant author information has been added to \`AUTHORS.rst\` and \`.zenodo.json\`.
 
               Please make sure you've read our [contributing guide](CONTRIBUTING.rst). We look forward to reviewing your Pull Request shortly ✨`

.github/workflows/main.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - main
     paths-ignore:
+      - .cruft.json
       - CHANGES.rst
       - README.rst
       - pyproject.toml
@@ -20,7 +21,6 @@ concurrency:
 
 permissions:
   contents: read
-  pull-requests: read
 
 jobs:
   lint:
@@ -68,6 +68,8 @@ jobs:
             tox-build: "py310-esmpy-coveralls"
           - python-version: "3.11"
             tox-build: "py311-esmpy-coveralls"
+#          - python-version: "3.12"
+#            tox-build: "py312-esmpy-coveralls"
     defaults:
       run:
         shell: bash -l {0}
@@ -176,6 +178,10 @@ jobs:
     runs-on: ubuntu-latest
     container: python:3-slim
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+        with:
+          gress-policy: audit
       - name: Coveralls Finished
         run: |
           python -m pip install --upgrade coveralls

.github/workflows/scorecard.yml

@@ -0,0 +1,82 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by separate terms of service, privacy
+# policy, and support documentation.
+
+name: Scorecard supply-chain security
+on:
+  # For Branch-Protection check. Only the default branch is supported. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
+  branch_protection_rule:
+  # To guarantee Maintained check is occasionally updated. See
+  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
+  schedule:
+    - cron: '41 8 * * 4'
+  push:
+    branches:
+      - main
+
+# Declare default permissions as read only.
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to upload the results to code-scanning dashboard.
+      security-events: write
+      # Needed to publish results and get a badge (see publish_results below).
+      id-token: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            api.github.com:443
+            api.osv.dev:443
+            api.securityscorecards.dev:443
+            fulcio.sigstore.dev:443
+            github.com:443
+            oss-fuzz-build-logs.storage.googleapis.com:443
+            rekor.sigstore.dev:443
+            tuf-repo-cdn.sigstore.dev:443
+            www.bestpractices.dev:443
+
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+        with:
+          persist-credentials: false
+
+      - name: Run analysis
+        uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          # This job step requires a personal access token named `OPENSSF_SCORECARD_TOKEN` with the following privileges:
+          # - Administration: Read-Only
+          # - Metadata: Read-Only
+          # - Webhooks: Read-Only
+          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat.
+          repo_token: ${{ secrets.OPENSSF_SCORECARD_TOKEN }}
+
+          # Public repositories:
+          #   - Publish results to OpenSSF REST API for easy access by consumers
+          #   - Allows the repository to include the Scorecard badge.
+          #   - See https://github.com/ossf/scorecard-action#publishing-results.
+          publish_results: true
+
+      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
+      # format to the repository Actions tab.
+      - name: Upload artifact
+        uses: actions/upload-artifact@694cdabd8bdb0f10b2cea11669e1bf5453eed0a6
+        with:
+          name: SARIF file
+          path: results.sarif
+          retention-days: 5
+
+      # Upload the results to GitHub's code scanning dashboard.
+      - name: Upload to code-scanning
+        uses: github/codeql-action/upload-sarif@e5f05b81d5b6ff8cfa111c80c22c5fd02a384118  # 3.23.0
+        with:
+          sarif_file: results.sarif

.github/workflows/tag-testpypi.yml

@@ -16,6 +16,10 @@ jobs:
     permissions:
       contents: write
     steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+        with:
+          egress-policy: audit
       - name: Checkout code
         uses: actions/checkout@v4.1.1
       - name: Create Release

.github/workflows/workflow-warning.yml

@@ -0,0 +1,69 @@
+name: Workflow Changes Warnings
+
+on:
+  # Note: potential security risk from this action using pull_request_target.
+  # Do not add actions in here which need a checkout of the repo, and do not use any caching in here.
+  # See: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
+  pull_request_target:
+    types:
+      - opened
+      - reopened
+      - synchronize
+    paths:
+      - .github/workflows/*.yml
+
+permissions:
+  contents: read
+
+jobs:
+  comment-concerning-workflow-changes:
+    name: Comment Concerning Workflow Changes
+    runs-on: ubuntu-latest
+    if: |
+      (github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name)
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            api.github.com:443
+      - name: Find comment
+        uses: peter-evans/find-comment@a54c31d7fa095754bfef525c0c8e5e5674c4b4b1 # v2.4.0
+        id: fc
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: |
+            This Pull Request modifies GitHub workflows and is coming from a fork.
+      - name: Create comment
+        if: |
+          (steps.fc.outputs.comment-id == '') &&
+          (!contains(github.event.pull_request.labels.*.name, 'approved')) &&
+          (github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name)
+        uses: peter-evans/create-or-update-comment@23ff15729ef2fc348714a3bb66d2f655ca9066f2 # v3.1.0
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            > **Warning**
+            > This Pull Request modifies GitHub Workflows and is coming from a fork.
+            **It is very important for the reviewer to ensure that the workflow changes are appropriate.**
+          edit-mode: replace
+      - name: Update comment
+        if: |
+          contains(github.event.pull_request.labels.*.name, 'approved')
+        uses: peter-evans/create-or-update-comment@23ff15729ef2fc348714a3bb66d2f655ca9066f2 # v3.1.0
+        with:
+          comment-id: ${{ steps.fc.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            > **Note**
+            > Changes have been approved by a maintainer.
+          reactions: |
+            hooray
+          edit-mode: append

.gitignore

@@ -78,6 +78,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/apidoc/modules.rst
+docs/apidoc/xscen*.rst
 
 # PyBuilder
 target/

.pre-commit-config.yaml

@@ -56,7 +56,7 @@ repos:
     rev: v0.3.9
     hooks:
       - id: blackdoc
-        additional_dependencies: [ 'black==23.12.1' ]
+        additional_dependencies: [ 'black==24.1.1' ]
         exclude: config.py
   - repo: https://github.com/adrienverge/yamllint.git
     rev: v1.33.0