From 54e58bd05f856032902121eea81368e07c18a297 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Wed, 14 Apr 2021 17:26:57 +0200 Subject: [PATCH 1/5] Use RELEASE.rst for admin project target group --- CONTRIBUTING.rst => RELEASE.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename CONTRIBUTING.rst => RELEASE.rst (100%) diff --git a/CONTRIBUTING.rst b/RELEASE.rst similarity index 100% rename from CONTRIBUTING.rst rename to RELEASE.rst From ce0ebfe57a393c4dfd2a0dbaa7f3549b0dfb7003 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Thu, 15 Apr 2021 18:10:54 +0200 Subject: [PATCH 2/5] Add pull request template Co-authored-by: Kyle Altendorf --- .github/PULL_REQUEST_TEMPLATE.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..cfa748f0 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,10 @@ +# Description + + +# Checklist + +* [ ] Make sure changes are covered by existing or new tests. +* [ ] For at least one Python version, make sure local test run is green. +* [ ] Create a file in `src/towncrier/newsfragments/`. Describe your + change and include important information. Your change will be included in the public release notes. +* [ ] Make sure all GitHub Actions checks are green (they are automatically checking all of the above). From 2c593b63b78b418cc03df9caf74dde809b34a6e6 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Wed, 14 Apr 2021 18:33:43 +0200 Subject: [PATCH 3/5] Rewrite CONTRIBUTING.rst (fix #342) * Address target group * Use CONTRIBUTING.rst for contributors only * Provide step-by-step instructions which can be used as a checklist * Add newsfragment Co-authored-by: Adi Roiban Co-authored-by: Kyle Altendorf --- CONTRIBUTING.rst | 131 ++++++++++++++++++++++++ src/towncrier/newsfragments/342.doc.rst | 1 + 2 files changed, 132 insertions(+) create mode 100644 CONTRIBUTING.rst create mode 100644 src/towncrier/newsfragments/342.doc.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..0dcbf4e7 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,131 @@ +Contributing to Towncrier +========================= + +Want to contribute to this project? Great! We'd love to hear from you! + +As a developer and user, you probably have some questions about our +project and how to contribute. +In this article we try to answer these and give you some recommendations. + + +Ways to communicate and contribute +---------------------------------- + +There are several options to contribute to this project: + +* Open a new topic on our `GitHub Discussions`_ page. + + Tell us about your ideas or ask questions there. + Discuss with us the next Towncrier release. + +* Help or comment on our GitHub `issues`_ tracker. + + There are certainly many issues where you can help with your expertise. + Or you would like to share your ideas with us. + +* Open a new issue using GitHub `issues`_ tracker. + + If you found a bug or have a new cool feature, describe your findings. + Try to be as descriptive as possible to help us understand your issue. + +* Check out the Freenode ``#twisted-dev`` IRC channel. + + If you prefer to discuss some topics personally, you may find the IRC + channel interesting. + +* Modify the code. + + If you would love to see the new feature in the next release, this is + probably the best way. + + +.. _modify_code: + +Modifying the code +------------------ + +The source code is managed using Git and is hosted on GitHub:: + + https://github.com/twisted/towncrier + git@github.com:twisted/towncrier.git + + +We recommend the following workflow: + +#. `Fork our project `_ on GitHub. + +#. Clone your forked Git repository (replace ``GITHUB_USER`` with your + account name on GitHub):: + + $ git clone git@github.com:GITHUB_USER/towncrier.git + + +#. Prepare a pull request: + + a. Create a new branch with:: + + $ git checkout -b + + b. Write your test cases and run the complete test suite, see the section + *Running the test suite* for details. + + c. Document any user facing changes in the ``README.rst`` file. + + d. Create a newsfragment in ``src/towncrier/newsfragments/`` describing the changes and containing information that are of interest for end-users. + + e. Create a `pull request`_. + Describe in the pull request what you did and why. If you have open questions, ask. + +#. Wait for feedback. If you receive any comments, address these. + +#. After your pull request is merged, delete your branch. + + +.. _testsuite: + +Running the test suite +---------------------- + +We use the `twisted.trial`_ module and `tox`_ to run tests against all supported +Python versions and operating systems. All test dependencies, other than tox, are installed +automatically. + +The following list contains some ways how to run the test suite: + +* To run all tests, use:: + + $ tox + + You may want to add the ``--skip-missing-interpreters`` option to avoid errors + when a specific Python interpreter version couldn't be found. + +* To get a complete list about the available targets, run:: + + $ tox -av + +* To run only a specific test only, use the ``towncrier.test.FILE.CLASS.METHOD`` syntax, + for example:: + + $ tox -- towncrier.test.test_project.InvocationTests.test_version + +* To run some quality checks before you create the pull request, + we recommend to use this call:: + + $ tox -e flake8,check-manifest,check-newsfragment + +* To investigate and debug errors, use the ``trial`` command like this:: + + $ trial -b towncrier + + This command creates a virtual environment and invokes a PDB session. + + + +.. ### Links + +.. _flake8: https://flake8.rtfd.io +.. _GitHub Discussions: https://github.com/twisted/towncrier/discussions +.. _issues: https://github.com/twisted/towncrier/issues +.. _pull request: https://github.com/twisted/towncrier/pulls +.. _tox: https://tox.rtfd.org/ +.. _twisted.trial: https://twistedmatrix.com/trac/wiki/TwistedTrial diff --git a/src/towncrier/newsfragments/342.doc.rst b/src/towncrier/newsfragments/342.doc.rst new file mode 100644 index 00000000..49e7f148 --- /dev/null +++ b/src/towncrier/newsfragments/342.doc.rst @@ -0,0 +1 @@ +Improve ``CONTRIBUTING.rst`` and add PR template. From 78c5f2d5644e3c09934c9ab5b6f2bc02d14c0b11 Mon Sep 17 00:00:00 2001 From: Adi Roiban Date: Sat, 16 Jul 2022 14:30:26 +0100 Subject: [PATCH 4/5] Add info about pre-commit --- CONTRIBUTING.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0dcbf4e7..abddc475 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -69,7 +69,7 @@ We recommend the following workflow: b. Write your test cases and run the complete test suite, see the section *Running the test suite* for details. - c. Document any user facing changes in the ``README.rst`` file. + c. Document any user facing changes in one of the `/docs/` files. d. Create a newsfragment in ``src/towncrier/newsfragments/`` describing the changes and containing information that are of interest for end-users. @@ -111,7 +111,14 @@ The following list contains some ways how to run the test suite: * To run some quality checks before you create the pull request, we recommend to use this call:: - $ tox -e flake8,check-manifest,check-newsfragment + $ tox -e check-manifest,check-newsfragment + +* Install `pre-commit `_ and activate:: + + $ pip install pre-commit + $ pre-commit + Or run as git hook + $ pre-commit install * To investigate and debug errors, use the ``trial`` command like this:: @@ -120,7 +127,6 @@ The following list contains some ways how to run the test suite: This command creates a virtual environment and invokes a PDB session. - .. ### Links .. _flake8: https://flake8.rtfd.io From 102626cd31be97c680f319e95bb9076bf14a08c0 Mon Sep 17 00:00:00 2001 From: Adi Roiban Date: Sat, 16 Jul 2022 14:33:47 +0100 Subject: [PATCH 5/5] Use upstream version. --- RELEASE.rst | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/RELEASE.rst b/RELEASE.rst index 31022e18..4a3090d9 100644 --- a/RELEASE.rst +++ b/RELEASE.rst @@ -50,7 +50,7 @@ Step-by-step - It is important to not use a fork so that pushed tags end up in the primary repository, server provided secrets for publishing to PyPI are available, and maybe more. -- If working on the first release candidate from this branch, create a PR named in the form ``Release 19.9``. +- If working on the first release candidate from this branch, create a PR named in the form ``Release 19.9.0``. - Request a review and address raised concerns until receiving an approval. @@ -75,9 +75,19 @@ Step-by-step - Edit ``src/towncrier/_version.py`` such as ``__version__ = Version('towncrier', 19, 9, 0)`` to remove the release candidate indication. - - Return to the towncrier build step and continue. + - Manually update the NEWS.rst by removing the `.rcN` version and update the release date. -- If the final release has been completed, continue below. + - Disable the actual check for `tox -e check-newsfragment` so that you will have a green test run. + + - Commit and push the changes to trigger the CI tests and make sure all are green. + + - Tag as ``19.9.0`` and push the tag to the primary repository. + + - This will result in another build which will publish to PyPI for the final release. + + - Confirm the presence of the release on PyPI. + +- If the final release has been completed, re-enable `tox -e check-newsfragment`. - Increment the patch version by one and set to a development version.