Skip to content

Commit acf9ad0

Browse files
larsonerlarsoner
authored
MAINT: Release 0.12.0 (#1088)
1 parent 3825d9f commit acf9ad0

File tree

8 files changed

+173
-271
lines changed

8 files changed

+173
-271
lines changed

‎.github/workflows/release.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Upload a Python Package using Twine when a release is created
2+
# Adapted from mne-bids-pipeline
3+
4+
name: Build
5+
on:
6+
release:
7+
types: [published]
8+
push:
9+
branches:
10+
- master
11+
pull_request:
12+
branches:
13+
- master
14+
15+
permissions:
16+
contents: read
17+
18+
jobs:
19+
package:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v3
23+
- name: Set up Python
24+
uses: actions/setup-python@v4
25+
with:
26+
python-version: '3.10'
27+
- name: Install dependencies
28+
run: |
29+
python -m pip install --upgrade pip
30+
pip install build twine
31+
- name: Build package
32+
run: python -m build --sdist --wheel
33+
- name: Check package
34+
run: twine check --strict dist/*
35+
- name: Check env vars
36+
run: |
37+
echo "Triggered by: ${{ github.event_name }}"
38+
- uses: actions/upload-artifact@v3
39+
with:
40+
name: dist
41+
path: dist
42+
43+
# PyPI on release
44+
pypi:
45+
needs: package
46+
runs-on: ubuntu-latest
47+
if: github.event_name == 'release'
48+
steps:
49+
- uses: actions/download-artifact@v3
50+
with:
51+
name: dist
52+
path: dist
53+
- name: Publish to PyPI
54+
uses: pypa/gh-action-pypi-publish@release/v1
55+
with:
56+
user: __token__
57+
password: ${{ secrets.PYPI_API_TOKEN }}

‎.github_changelog_generator‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
project=sphinx-gallery
2+
user=sphinx-gallery
3+
add-sections={"documentation":{"prefix":"**Documentation**","labels":["documentation"]},"maintenance":{"prefix": "**Project maintenance**","labels":["maintenance"]}}
4+
max-issues=200
5+
issues=no

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ coverage.xml
4545
*.orig
4646
.pytest_cache
4747
CHANGELOG.md
48+
CHANGELOG.rst
4849
junit-results.xml
4950

5051
# Translations

‎CHANGES.rst‎

Lines changed: 62 additions & 188 deletions
Large diffs are not rendered by default.

‎MANIFEST.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,4 @@ exclude __pycache__
3131
recursive-exclude */gen_modules *
3232
exclude gen_modules
3333
exclude .DS_store
34+
exclude .github_changelog_generator

‎README.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ An incomplete list:
3131
3232
* `Apache TVM <https://tvm.apache.org/docs/tutorial/index.html>`_
3333
* `Astropy <https://docs.astropy.org/en/stable/generated/examples/index.html>`_
34-
* `Biotite <https://www.biotite-python.org/examples/gallery/index.html>`_
3534
* `Auto-sklearn <https://automl.github.io/auto-sklearn/master/examples/index.html>`_
35+
* `Biotite <https://www.biotite-python.org/examples/gallery/index.html>`_
3636
* `Cartopy <https://scitools.org.uk/cartopy/docs/latest/gallery/>`_
3737
* `Fury <https://fury.gl/latest/auto_examples/index.html>`_
3838
* `GIMLi <https://www.pygimli.org/_examples_auto/index.html>`_
@@ -55,9 +55,9 @@ An incomplete list:
5555
* `Scikit-learn <http://scikit-learn.org/stable/auto_examples/index.html>`_
5656
* `SimPEG <https://docs.simpeg.xyz/content/examples/>`_
5757
* `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/auto_examples/index.html>`_
58+
* `SunPy <https://docs.sunpy.org/en/stable/generated/gallery/index.html>`_
5859
* `Tonic <https://tonic.readthedocs.io/en/latest/auto_examples/index.html>`_
5960
* `TorchIO <https://torchio.readthedocs.io/auto_examples/index.html>`_
60-
* `SunPy <https://docs.sunpy.org/en/stable/generated/gallery/index.html>`_
6161

6262
.. projects_list_end
6363

‎doc/maintainers.rst‎

Lines changed: 44 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -15,99 +15,61 @@ How to make a release
1515

1616
.. highlight:: console
1717

18-
Check credentials and prerequisites
19-
-----------------------------------
18+
1. Update ``CHANGES.rst`` and version in a PR
19+
---------------------------------------------
2020

21-
Sphinx Gallery is `hosted on the pypi repository <https://pypi.org/project/sphinx-gallery/>`_.
22-
To create a new release of Sphinx Gallery, you need to do these things:
23-
You should double-check a few things to make sure that you can create
24-
a new release for Sphinx Gallery.
21+
1. Use `github_changelog_generator
22+
<https://github.com/github-changelog-generator/github-changelog-generator#installation>`_ to
23+
gather all merged pull requests and closed issues during the development
24+
cycle. You will likely need to `generate a Github token <https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token>`_
25+
as Github only allows 50 unauthenticated requests per hour. In the
26+
command below ``<version>`` is the current (not development) version of
27+
the package, e.g., ``0.6.0``. The changelog can generated with the following::
2528

26-
1. Ensure that you **registered an account** on `the PyPI index <https://pypi.org/account/register/>`_.
27-
2. Ensure you have **push access** to the
28-
`Sphinx Gallery pypi repository <https://pypi.org/project/sphinx-gallery/>`_.
29-
Ask one of the Sphinx Gallery core developers if you do not.
30-
3. Install the `GitHub Changelog Generator <https://github.com/github-changelog-generator/github-changelog-generator#installation>`_.
31-
This is a small tool written in Ruby to generate a markdown list of recent changes.
32-
4. Install `the twine package <https://twine.readthedocs.io/en/latest/>`_. This is
33-
a package that helps you
34-
bundle and push new Python package distributions to pip.
29+
github_changelog_generator --since-tag=v<version> --token <your-40-digit-token>
3530

31+
To avoid the need to pass ``--token``, you can use ``export CHANGELOG_GITHUB_TOKEN=<your-40-digit-token>`` instead.
3632

37-
Prepare for release
38-
-------------------
39-
1. Update ``CHANGES.rst``
33+
2. Iteratively update PR labels on GitHub and regenerate ``CHANGELOG.md`` so
34+
that PRs are categorized correctly. The labels we currently use are:
4035

41-
1. Use `github_changelog_generator
42-
<https://github.com/github-changelog-generator/github-changelog-generator#installation>`_ to
43-
gather all merged pull requests and closed issues during the development
44-
cycle. You will likely need to `generate a Github token <https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token>`_
45-
as Github only allows 50 unauthenticated requests per hour. In the
46-
command below ``<version>`` is the current (not development) version of
47-
the package, e.g., ``0.6.0``. We do this because our failing discipline
48-
of writing in the CHANGES.rst all relevant changes, this helps our
49-
memory. It is a good idea to add appropriate labels (e.g., 'BUG') to
50-
issues and pull requests so they are categorized correctly in the
51-
CHANGES.rst generated. ::
36+
``bug``
37+
For fixed bugs.
38+
``enhancement``
39+
For enhancements
40+
``maintenance``
41+
For general project maintenance (e.g., CIs)
42+
``documentation``
43+
For documentation improvements.
44+
45+
Once all PRs land in one of these categories, manually edit CHANGELOG.md to
46+
look reasonable if necessary.
5247

53-
github_changelog_generator -u sphinx-gallery -p sphinx-gallery --since-tag=v<version> --token <your-40-digit-token>
48+
3. Propagate the relevant changes to `CHANGES.rst <https://github.com/sphinx-gallery/sphinx-gallery/blob/master/CHANGES.rst>`_.
49+
You can easily convert it RST with pandoc::
5450

55-
2. Edit CHANGELOG.md to look reasonable (it will be used later). It's a
56-
good idea to add labels to issues and pull requests so
57-
`github_changelog_generator` can correctly categorize them in in the
58-
CHANGES.rst file generated.
51+
pandoc CHANGELOG.md --wrap=none -o CHANGELOG.rst
5952

60-
3. Propagate the relevant changes to `CHANGES.rst <https://github.com/sphinx-gallery/sphinx-gallery/blob/master/CHANGES.rst>`_.
61-
You can easily convert it RST with pandoc::
53+
Then copy just the sections to ``CHANGES.rst``. **Keep ``CHANGELOG.md`` for
54+
later.**
6255

63-
pandoc CHANGELOG.md --wrap=none -o CHANGELOG.rst
56+
4. Update the version in ``sphinx_gallery/__init__.py``, which should end in
57+
``.dev0``. You should replace ``.dev0`` with ``0`` to obtain a semantic
58+
version (e.g., ``0.12.dev0`` to ``0.12.0``).
6459

65-
2. Build the docs cleanly
60+
5. Open a PR with the above **changelog** and **version** changes (along with
61+
any updates to this ``maintainers.rst`` document!).
6662

67-
Make sure to clean all and have a clean build. Double-check visually that
68-
everything looks right.
63+
6. Make sure CIs are green.
6964

70-
3. Double check CIs
65+
7. Check that the built documentation looks correct.
7166

72-
Make sure CIs are green on the master branch.
67+
8. Get somebody else to make sure all looks well, and merge this pull request.
7368

74-
4. Update version
75-
76-
Update the version in ``sphinx_gallery/__init__.py``, which should end in
77-
``.dev0``. You should remove ``.dev0``, and the numbers that remain will
78-
become the version for this release.
79-
80-
5. Open a Pull Request that contains the two changes we've made above
81-
82-
The **version bump** and **the CHANGELOG update** should be in the PR.
83-
Get somebody else to make sure all looks well, and merge this pull request.
84-
85-
Finalize the release
86-
--------------------
87-
88-
1. Create the new release on PyPI
89-
90-
* Build a source distribution and an ``any`` wheel::
91-
92-
git clean -xdf
93-
python setup.py sdist bdist_wheel
94-
95-
* Check the release::
96-
97-
twine check dist/sphinx-gallery-<version>.*
98-
99-
``<version>`` should be the release version, e.g., ``0.7.0``, and it
100-
should check both the source distribution and the wheel.
101-
102-
* Upload to PyPI::
103-
104-
twine upload dist/*
105-
106-
Again, ``<version>`` should be the release version, e.g., ``0.7.0``.
107-
108-
* Confirm that the new version of Sphinx Gallery
109-
`is posted to pypi <https://pypi.org/project/sphinx-gallery/>`_.
69+
2. Finalize the release
70+
------------------------
11071

72+
1. Make sure CIs are green following the "Release" PR.
11173
2. Create a new release on GitHub
11274

11375
* Go to the `Draft a new release <https://github.com/sphinx-gallery/sphinx-gallery/releases/new>`_ page.
@@ -116,9 +78,11 @@ Finalize the release
11678
* The **description** should contain the markdown changelog
11779
you generated above (in the ``CHANGELOG.md`` file).
11880
* Click **Publish release** when you are done.
81+
* Confirm that the new version of Sphinx Gallery
82+
`is posted to PyPI <https://pypi.org/project/sphinx-gallery/#history>`_.
11983

120-
3. Now that the releases are complete, we need to switch the "master" branch back into a developer
121-
mode. Bump the `Sphinx Gallery version number <https://github.com/sphinx-gallery/sphinx-gallery/blob/master/sphinx_gallery/__init__.py>`_
84+
3. Now that the releases are complete, we need to switch the `master`` branch
85+
back into a developer mode. Bump the `Sphinx Gallery version number <https://github.com/sphinx-gallery/sphinx-gallery/blob/master/sphinx_gallery/__init__.py>`_
12286
to the next minor (or major) release and append ``.dev0`` to the end, and make a PR for this change.
12387

12488
4. Celebrate! You've just released a new version of Sphinx Gallery!

‎sphinx_gallery/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
import os
77
# dev versions should have "dev" in them, stable should not.
88
# doc/conf.py makes use of this to set the version drop-down.
9-
__version__ = '0.12.0.dev0'
9+
__version__ = '0.12.0'
1010

1111

1212
def glr_path_static():

0 commit comments

Comments
 (0)