From 40d0ade2d9d0ab6d8d8b3df759945511042f86b5 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Tue, 6 Feb 2018 22:13:04 -0200 Subject: [PATCH] Add changelog/README.rst and streamline our PR template text This streamlines the PR template text and adds a more in-depth explanation about how the changelog entries work because this topic is a common source of confusion: - How to name the files. - Which formatting to use (people in general assume it is Markdown). - Recommend adding `.rst` extension to changelog files to help with the above (`towncrier` doesn't care). This was heavily inspired by the excellent python-trio/trio docs. --- .github/PULL_REQUEST_TEMPLATE.md | 19 ++++++------- changelog/{1810.bugfix => 1810.bugfix.rst} | 0 changelog/{3166.trivial => 3166.trivial.rst} | 0 changelog/{985.trivial => 985.trivial.rst} | 0 changelog/README.rst | 30 ++++++++++++++++++++ 5 files changed, 39 insertions(+), 10 deletions(-) rename changelog/{1810.bugfix => 1810.bugfix.rst} (100%) rename changelog/{3166.trivial => 3166.trivial.rst} (100%) rename changelog/{985.trivial => 985.trivial.rst} (100%) create mode 100644 changelog/README.rst diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 690426d68..64769b8e2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,15 +1,14 @@ Thanks for submitting a PR, your contribution is really appreciated! -Here's a quick checklist that should be present in PRs: +Here's a quick checklist that should be present in PRs (you can delete this text from the final description, this is +just a guideline): -- [ ] Add a new news fragment into the changelog folder - * name it `$issue_id.$type` for example (588.bugfix) - * if you don't have an issue_id change it to the pr id after creating the pr - * ensure type is one of `removal`, `feature`, `bugfix`, `vendor`, `doc` or `trivial` - * Make sure to use full sentences with correct case and punctuation, for example: "Fix issue with non-ascii contents in doctest text files." -- [ ] Target: for `bugfix`, `vendor`, `doc` or `trivial` fixes, target `master`; for removals or features target `features`; -- [ ] Make sure to include reasonable tests for your change if necessary +- [ ] Create a new changelog file into the `changelog` folder, with a name like `..rst`. See [changelog/README.rst](/changelog/README.rst) for details. +- [ ] Target the `master` branch for bug fixes, documentation updates and trivial changes. +- [ ] Target the `features` branch for new features and removals/deprecations. +- [ ] Include documentation when adding new features. +- [ ] Include new tests or update existing tests when applicable. -Unless your change is a trivial or a documentation fix (e.g., a typo or reword of a small section) please: +Unless your change is trivial or a small documentation fix (e.g., a typo or reword of a small section) please: -- [ ] Add yourself to `AUTHORS`, in alphabetical order; +- [ ] Add yourself to `AUTHORS` in alphabetical order; diff --git a/changelog/1810.bugfix b/changelog/1810.bugfix.rst similarity index 100% rename from changelog/1810.bugfix rename to changelog/1810.bugfix.rst diff --git a/changelog/3166.trivial b/changelog/3166.trivial.rst similarity index 100% rename from changelog/3166.trivial rename to changelog/3166.trivial.rst diff --git a/changelog/985.trivial b/changelog/985.trivial.rst similarity index 100% rename from changelog/985.trivial rename to changelog/985.trivial.rst diff --git a/changelog/README.rst b/changelog/README.rst new file mode 100644 index 000000000..ec1c7f617 --- /dev/null +++ b/changelog/README.rst @@ -0,0 +1,30 @@ +This directory contains "newsfragments" which are short that contain a small **ReST**-formatted +text that will be added to the next ``CHANGELOG``. + +The ``CHANGELOG`` will be read by users, so this description should be aimed to pytest users +instead of describing internal changes which are only relevant to the developers. + +Make sure to use full sentences with correct case and punctuation, for example: *Fix issue with non-ascii contents in doctest text files.* + +Each file should be named like ``..rst``, where +```` is an issue number, and ```` is one of: + +* ``feature``: new user facing features, like new command-line options and new behavior. +* ``bugfix``: fixes a reported bug. +* ``doc``: documentation improvement, like rewording an entire session or adding missing docs. +* ``removal``: feature deprecation or removal; +* ``vendor``: vendoring news; +* ``trivial``: fixing a small typo or internal change that might be noteworthy. + +So for example: ``123.feature.rst``, ``456.bugfix.rst``. + +If your PR fixes an issue, use that number here. If there is no issue, +then after you submit the PR and get the PR number you can add a +changelog using that instead. + +If you are not sure what issue type to use, don't hesitate to ask in your PR. + +Note that the ``towncrier`` tool will automatically +reflow your text, so it will work best if you stick to a single paragraph, but multiple sentences and links are OK +and encouraged. You can install ``towncrier`` and then run ``towncrier --draft`` +if you want to get a preview of how your change will look in the final release notes.