Merge pull request datalad#49 from datalad/dataladgh-48

Templates for using datalad/release-action

.datalad-release-action.yaml

@@ -0,0 +1,45 @@
+fragment-directory: changelog.d
+
+categories:
+  - name: 💥 Breaking Changes
+    bump: major
+    label: semver-major
+    label-color: C5000B
+    label-description: Increment the major version when merged
+  - name: 🚀 Enhancements and New Features
+    bump: minor
+    label: semver-minor
+    label-color: F1A60E
+    label-description: Increment the minor version when merged
+  - name: 🐛 Bug Fixes
+    label: semver-patch
+    label-color: "870048"
+    label-description: Increment the patch version when merged
+  - name: 🔩 Dependencies
+    label: semver-dependencies
+    label-color: 8732bc
+    label-description: Update one or more dependencies' versions
+  - name: 📝 Documentation
+    label: semver-documentation
+    label-color: cfd3d7
+    label-description: Changes only affect the documentation
+  - name: 🏠 Internal
+    label: semver-internal
+    label-color: "696969"
+    label-description: Changes only affect the internal API
+  - name: 🏎 Performance
+    label: semver-performance
+    label-color: f4b2d8
+    label-description: Improve performance of an existing feature
+  - name: 🧪 Tests
+    label: semver-tests
+    label-color: ffd3cc
+    label-description: Add or improve existing tests
+
+extra-labels:
+  - name: release
+    color: 007f70
+    description: Create a release when this pr is merged
+  - name: CHANGELOG-missing
+    color: 5B0406
+    description: When a PR does not contain add a changelog item, yet

.github/workflows/add-changelog-snippet.yml

@@ -0,0 +1,33 @@
+name: Add changelog.d snippet
+
+on:
+  # This action should be run in workflows triggered by `pull_request_target`
+  # (not by regular `pull_request`!)
+  pull_request_target:
+    # Run whenever the PR is pushed to, receives a label, or is created with
+    # one or more labels:
+    types: [synchronize, labeled]
+
+# Prevent the workflow from running multiple jobs at once when a PR is created
+# with multiple labels:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  add:
+    runs-on: ubuntu-latest
+    # Only run on PRs that have the "CHANGELOG-missing" label:
+    if: contains(github.event.pull_request.labels.*.name, 'CHANGELOG-missing')
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+
+      - name: Add changelog snippet
+        uses: datalad/release-action/add-changelog-snippet@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          rm-labels: CHANGELOG-missing

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Auto-release on PR merge
+
+on:
+  # This action should be run in workflows triggered by `pull_request_target`
+  # (not by regular `pull_request`!)
+  pull_request_target:
+    branches:
+      # Create a release whenever a PR is merged into one of these branches:
+      - main
+    types:
+      - closed
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    # Only run for merged PRs with the "release" label:
+    if: github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release')
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v3
+        with:
+          # Check out all history so that the previous release tag can be
+          # found:
+          fetch-depth: 0
+
+      - name: Prepare release
+        uses: datalad/release-action/release@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          #pypi-token: ${{ secrets.PYPI_TOKEN }}

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+## Releasing with GitHub Actions and pull requests
+
+New releases of this project are created via a GitHub Actions workflow using
+[datalad/release-action](https://github.com/datalad/release-action), which was
+inspired by [`auto`](https://github.com/intuit/auto).  Whenever a pull request
+is merged into `main` that has the "`release`" label, the workflow updates the
+changelog based on the pull requests since the previous release, commits the
+results, tags the new commit with the next version number, creates a GitHub
+release for the tag, builds an sdist & wheel for the project, and uploads the
+sdist & wheel to PyPI.
+
+### CHANGELOG entries and labelling pull requests
+
+This project uses [scriv](https://github.com/nedbat/scriv/) to maintain the
+[CHANGELOG.md](./CHANGELOG.md) file.  Adding the label `CHANGELOG-missing` to a
+PR triggers a workflow to add a new `scriv` changelog fragment under
+`changelog.d/` using the PR title as the content.  That produced changelog
+snippet can subsequently be tuned to improve the prospective CHANGELOG entry.
+The changelog section that the fragment is added under depends on the `semver-`
+label added to the PR:
+
+- `semver-minor` — for changes corresponding to an increase in the minor
+  version component
+- `semver-patch` — for changes corresponding to an increase in the patch/micro
+  version component
+- `semver-internal` — for changes only affecting the internal API
+- `semver-documentation` — for changes only affecting the documentation
+- `semver-tests` — for changes to tests
+- `semver-dependencies` — for updates to dependency versions
+- `semver-performance` — for performance improvements

README.md

@@ -37,6 +37,10 @@ adjust as necessary. A good approach is to
 - Adjust the documentation in `docs/source/index.rst`. Refer to [`docs/README.md`](docs/README.md) for more information on documentation building, testing and publishing.
 - Replace this README, and/or update the links in the badges at the top.
 - Update `setup.cfg` with appropriate metadata on the new extension.
+- Generate GitHub labels for use by the "Add changelog.d snippet" and
+  "Auto-release on PR merge" workflows by using the code in the
+  `datalad/release-action` repository [as described in its
+  README](https://github.com/datalad/release-action#command-labels).
 
 You can consider filling in the provided [.zenodo.json](.zenodo.json) file with
 contributor information and [meta data](https://developers.zenodo.org/#representation)
@@ -45,3 +49,8 @@ to acknowledge contributors and describe the publication record that is created
 by archiving it using [zenodo.org](https://zenodo.org/). You may also want to
 consider acknowledging contributors with the
 [allcontributors bot](https://allcontributors.org/docs/en/bot/overview).
+
+# Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) if you are interested in internals or
+contributing to the project.

changelog.d/scriv.ini

@@ -0,0 +1,6 @@
+[scriv]
+fragment_directory = changelog.d
+entry_title_template = file: templates/entry_title.md.j2
+new_fragment_template = file: templates/new_fragment.md.j2
+format = md
+categories = 💥 Breaking Changes, 🚀 Enhancements and New Features, 🐛 Bug Fixes, 🔩 Dependencies, 📝 Documentation, 🏠 Internal, 🏎 Performance, 🧪 Tests

changelog.d/templates/entry_title.md.j2

@@ -0,0 +1 @@
+{{ version if version else "VERSION" }} ({{ date.strftime('%Y-%m-%d') }})

changelog.d/templates/new_fragment.md.j2

@@ -0,0 +1,10 @@
+<!-- Uncomment the section that is right (remove the HTML comment wrapper).-->
+{% for cat in config.categories -%}
+<!--
+### {{ cat }}
+
+- Describe change, possibly reference closed/related issue/PR.
+  Fixes https://github.com/datalad/datalad-helloworld/issues/XXX via
+  https://github.com/datalad/datalad-helloworld/pull/XXX (by [@GITHUBHANDLE](https://github.com/GITHUBHANDLE))
+-->
+{% endfor -%}