From f6100f0c3c0bbc8ce5dc775569c07b02ac27241e Mon Sep 17 00:00:00 2001 From: Kyle Benesch <4b796c65+github@gmail.com> Date: Sat, 11 May 2024 02:01:10 -0700 Subject: [PATCH] Move maintainers guide into CONTRIBUTING.md and add PR templates Removed release steps on manually testing before a release because CI handles these tests automatically. Release guide now suggests making a PR for updates and using the tests from those. Removed mention of `make doctest`. Whatever tools this relied on were never set up. Nothing was in the doc directory to be tested. Release guide no longer suggests adding a signature. --- .github/pull_request_template.md | 9 +++ CONTRIBUTING.md | 71 ++++++++++++++++++++++- doc/devel/make_release.rst | 98 -------------------------------- doc/links_names.inc | 16 ------ 4 files changed, 79 insertions(+), 115 deletions(-) create mode 100644 .github/pull_request_template.md delete mode 100644 doc/devel/make_release.rst delete mode 100644 doc/links_names.inc diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..1e861e22 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,9 @@ +### Pull Request Checklist + +- [ ] Read and follow the [CONTRIBUTING.md](https://github.com/matthew-brett/delocate/blob/master/CONTRIBUTING.md) guide +- [ ] Mentioned relevant [issues](https://github.com/matthew-brett/delocate/issues) +- [ ] Append public facing changes to [Changelog.md](https://github.com/matthew-brett/delocate/blob/master/Changelog.md) +- [ ] Ensure new features are covered by tests +- [ ] Ensure fixes are verified by tests + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e0cc1c2..cb0a1ef2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing +## Contributors guide + This project uses [pre-commit](https://pre-commit.com/) hooks. You should install these hooks by running the following commands from the project directory: @@ -8,8 +10,75 @@ pip install pre-commit pre-commit install ``` -Installing IDE plugins supporting [Mypy](https://mypy.readthedocs.io/en/stable/) and [Ruff](https://docs.astral.sh/ruff/) is recommend. +Installing IDE plugins supporting [Mypy](https://mypy.readthedocs.io/en/stable/) and [Ruff](https://docs.astral.sh/ruff/) is recommend but not required. +These will be verified by GitHub Actions during a pull request if you are unable to check them locally. Documentation follows the [Numpydoc Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html). +All public functions must have full documentation. +All private functions must have at least a brief description. The `wheel_makers` directory holds scripts used to make test data. GitHub Actions will generate this data and upload it as an artifact named `delocate-tests-data`. This can be used to create and commit new test wheels for MacOS even if you don't have access to your own system. + +Use [pathlib](https://docs.python.org/3/library/pathlib.html) for any new code using paths. +Refactor any touched functions to use pathlib when it does not break backwards compatibility. +Prefer using `PurePosixPath` to handle relative library paths returned from MacOS tools such as `otool`. + +All new functions must have [type hints](https://mypy.readthedocs.io/en/stable/getting_started.html). +All touched functions must be refactored to use type hints, including test functions. + +This codebase includes legacy code from the Python 2 era. +Old code should be refactored to use modern standards when touched. + +## Maintainers guide + +This section is only relevant for maintainers with repo access. + +Ensure pre-commit hooks are up-to-date by running `pre-commit autoupdate`. + +### Guide to making a Delocate release + +A guide for maintainers who are doing a Delocate release. + +#### Release checklist + +- Review the open list of [issues](http://github.com/matthew-brett/delocate/issues). + Check whether there are outstanding issues that can be closed, and whether there are any issues that should delay the release. + Label them! + +- Review and update the release notes. + Review and update the `Changelog` file. + Get a partial list of contributors with something like:: + + git shortlog -ns 0.6.0.. + + where `0.6.0` was the last release tag name. + + Then manually go over `git shortlog 0.6.0..` to make sure the release notes + are as complete as possible and that every contributor was recognized. + +- Use the opportunity to update the `.mailmap` file if there are any + duplicate authors listed from `git shortlog -ns`. + +- Add any new authors to the `AUTHORS` file. Add any new entries to the `THANKS` file. + +- Check the copyright years in `LICENSE` + +- Make sure all tests are passing for the latest commit intended to be released. + The recommended way to do this is to make a PR for the release. + Once the PR is merged then the release is now ready. + +#### Doing the release + +You might want to make tag the release commit on your local machine, push to [PyPI](https://pypi.org/project/delocate), review, fix, rebase, until all is good. +Then and only then do you push to upstream on github. + +- Make an annotated tag for the release with tag of form `0.6.0`:: + + git tag -a 0.6.0 + +- Push the tag with something like `git push origin 0.6.0` and that tag will be automatically deployed to PyPI. + +- Check how everything looks on PyPI - the description, the packages. + If anything doesn't look right then yank the release and upload with the patch version incremented. + +- Announce to the mailing lists. With fear and trembling. diff --git a/doc/devel/make_release.rst b/doc/devel/make_release.rst deleted file mode 100644 index 6f00883b..00000000 --- a/doc/devel/make_release.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. _release-guide: - -*********************************** -Guide to making a Delocate release -*********************************** - -A guide for developers who are doing a Delocate release - -.. _release-checklist: - -Release checklist -================= - -* Review the open list of `delocate issues`_. Check whether there are - outstanding issues that can be closed, and whether there are any issues that - should delay the release. Label them ! - -* Review and update the release notes. Review and update the :file:`Changelog` - file. Get a partial list of contributors with something like:: - - git shortlog -ns 0.6.0.. - - where ``0.6.0`` was the last release tag name. - - Then manually go over ``git shortlog 0.6.0..`` to make sure the release notes - are as complete as possible and that every contributor was recognized. - -* Use the opportunity to update the ``.mailmap`` file if there are any - duplicate authors listed from ``git shortlog -ns``. - -* Add any new authors to the ``AUTHORS`` file. Add any new entries to the - ``THANKS`` file. - -* Check the copyright years in ``doc/conf.py`` and ``LICENSE`` - -* If you have travis-ci_ building set up you might want to push the code in its - current state to a branch that will build, e.g:: - - git branch -D pre-release-test # in case branch already exists - git co -b pre-release-test - -* Clean:: - - git clean -fxd - -* Make sure all tests pass on your local machine (from the delocate root - directory):: - - pytest --pyargs delocate - - Do this on a Python 2 and Python 3 setup. Check on oldest supported version - of macOS. Check on newest supported version. - -* Run the same tests after installing into a virtualenv, to test that - installing works correctly:: - - mkvirtualenv delocate-test - pip install pytest wheel - git clean -fxd - pip install -e . - mkdir for_test - cd for_test - pytest --pyargs delocate - -* Check the documentation doctests:: - - cd doc - make doctest - cd .. - -* The release should now be ready. - -Doing the release -================= - -You might want to make tag the release commit on your local machine, push to -pypi_, review, fix, rebase, until all is good. Then and only then do you push -to upstream on github. - -* Make a signed tag for the release with tag of form ``0.6.0``:: - - git tag -s 0.6.0 - - The package version will be derived from the tag automatically. - -* Push the tag with something like ``git push origin 0.6.0`` and that tag will - be automatically deployed to PyPI. - -* Check how everything looks on PyPI - the description, the packages. - If anything doesn't look right then yank the release and upload with the - patch version incremented. - -* Announce to the mailing lists. With fear and trembling. - -.. _setuptools intro: http://packages.python.org/an_example_pypi_project/setuptools.html -.. _twine: https://pypi.python.org/pypi/twine - -.. include:: ../links_names.inc diff --git a/doc/links_names.inc b/doc/links_names.inc deleted file mode 100644 index 6f6684f7..00000000 --- a/doc/links_names.inc +++ /dev/null @@ -1,16 +0,0 @@ -.. This (-*- rst -*-) format file contains commonly used link targets - and name substitutions. It may be included in many files, - therefore it should only contain link targets and name - substitutions. Try grepping for "^\.\. _" to find plausible - candidates for this list. - -.. NOTE: reST targets are - __not_case_sensitive__, so only one target definition is needed for - nipy, NIPY, Nipy, etc... - -.. _delocate github: http://github.com/matthew-brett/delocate -.. _delocate pypi: https://pypi.org/project/delocate -.. _delocate issues: http://github.com/matthew-brett/delocate/issues -.. _delocate travis-ci: https://travis-ci.org/matthew-brett/delocate - -.. vim:syntax=rst