diff --git a/.datalad-release-action.yaml b/.datalad-release-action.yaml new file mode 100644 index 0000000..4c4de3d --- /dev/null +++ b/.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 diff --git a/.github/workflows/add-changelog-snippet.yml b/.github/workflows/add-changelog-snippet.yml new file mode 100644 index 0000000..b524312 --- /dev/null +++ b/.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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..32bfd96 --- /dev/null +++ b/.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 }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c8ebd46 --- /dev/null +++ b/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 diff --git a/README.md b/README.md index 9284253..8e6bd02 100644 --- a/README.md +++ b/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. diff --git a/changelog.d/scriv.ini b/changelog.d/scriv.ini new file mode 100644 index 0000000..a9dcbdd --- /dev/null +++ b/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 diff --git a/changelog.d/templates/entry_title.md.j2 b/changelog.d/templates/entry_title.md.j2 new file mode 100644 index 0000000..3e7cb9d --- /dev/null +++ b/changelog.d/templates/entry_title.md.j2 @@ -0,0 +1 @@ +{{ version if version else "VERSION" }} ({{ date.strftime('%Y-%m-%d') }}) diff --git a/changelog.d/templates/new_fragment.md.j2 b/changelog.d/templates/new_fragment.md.j2 new file mode 100644 index 0000000..27d0e93 --- /dev/null +++ b/changelog.d/templates/new_fragment.md.j2 @@ -0,0 +1,10 @@ + +{% for cat in config.categories -%} + +{% endfor -%}