chore: update CONTRIBUTING.md and add pull_request_template.md

.github/CONTRIBUTING.rst

@@ -4,89 +4,67 @@ knowing.
 Reporting a bug / requesting a feature / asking a question
 ----------------------------------------------------------
 
-Go `open an issue <https://github.com/nat-n/poethepoet/issues>`_ or
-`start a discussion <https://github.com/nat-n/poethepoet/discussions>`_ and
-I’ll probably reply soon.
+Go `open an issue <https://github.com/nat-n/poethepoet/issues>`_ or `start a discussion <https://github.com/nat-n/poethepoet/discussions>`_ and I’ll probably reply soon.
 
 Contributing to the docs
 ------------------------
 
-Just make a PR with your proposed changes targeting the main branch. 
-The [documentation website](https://poethepoet.natn.io/) will update once your
-PR is merged.
+Just make a PR with your proposed changes targeting the main branch. The `documentation website <https://poethepoet.natn.io/>`_ will update once your PR is merged.
 
 Contributing code
 -----------------
 
 Preface
 ~~~~~~~
 
-If you’re willing to contribute your ideas and effort to making poethepoet
-better, then that’s awesome and I’m grateful. I don’t have all the answers so
-it’s particularly important for this project to benefit from diverse
-perspectives and technical expertise.
+If you’re willing to contribute your ideas and effort to making poethepoet better, then that’s awesome and I’m grateful. I don’t have all the answers so it’s particularly important for this project to benefit from diverse perspectives and technical expertise.
 
-However please be aware that a lot of thought has gone into the architecture of
-poethepoet, and whilst I know it’s not perfect, and I am very interested in
-alternative perspectives, I do have strong (and I hope reasonable) opinions
-about how certain things should work. This particularly applies to naming and
-internal APIs. There is a lot to consider in terms of making sure the tool stays
-simple, flexible, and performant. So please don’t be offended if there is some
-push back.
+However please be aware that a lot of thought has gone into the architecture of poethepoet, and whilst I know it’s not perfect, and I am very interested in alternative perspectives, I do have strong (and I hope reasonable) opinions about how certain things should work. This particularly applies to naming and internal APIs. There is a lot to consider in terms of making sure the tool stays simple, flexible, and performant. So please don’t be offended if there is some push back.
 
 Development process
 ~~~~~~~~~~~~~~~~~~~
 
-1. If your planned changes entail non-trivial UI or internal API changes then
- it’s a good idea to bring them up for discussion as a
- `GitHub issue <https://github.com/nat-n/poethepoet/issues>`_ first.
+1. If your planned changes entail non-trivial UI or internal API changes then it’s a good idea to bring them up for discussion as a `GitHub issue <https://github.com/nat-n/poethepoet/issues>`_ first.
 
-2. Fork and clone the repo, and create a feature or bugfix branch off of the
- *development* branch.
+2. Fork and clone the repo, and create a feature or bugfix branch off of the *development* branch.
 
-3. Double check that you’re starting from the *development* branch, and not from
- the the *main* branch.
+3. Double check that you’re starting from the *development* branch, and not from the the *main* branch.
 
-4. Run ``poetry install`` to setup your development environment.
- (`install poetry <https://python-poetry.org/docs/#installation>`__)
+4. Run ``poetry install`` to setup your development environment. (`install poetry <https://python-poetry.org/docs/#installation>`__)
 
 5. Do your code.
 
-6. If you’ve added a feature then before it can be including in a release we
- will need:
+6. If you’ve added a feature then before it can be including in a release we will need:
 
  a. a feature test along the same lines as the examples in the tests dir,
  b. to update documentation.
 
-5. Run ``poe check`` to check that you haven’t broken anything that will
- block the CI pipeline.
+5. Run ``poe check`` to check that you haven’t broken anything that will block the CI pipeline.
 
-6. Create a commit with a clear commit message that describes the commit
- contents.
+6. Create a commit with a clear commit message that describes the commit contents.
 
 7. Open a PR on GitHub.
 
+.. seealso::
+
+ You can also open a draft PR proposing incomplete changes to recieve feedback.
+
 Pull requests
 ~~~~~~~~~~~~~
 
-There isn’t currently a pull request template, but please try and be descriptive
-about what problem you’re solving and how, and reference related issues.
+There isn’t currently a pull request template, but please try and be descriptive about what problem you’re solving and how, and reference related issues.
 
-In some cases it might be acceptable to merge code to *development* to make a
-pre-release from it without including full automated tests and documentation.
-However this is a special case, because it blocks further releases from the
-*development* branch until the tests and docs are there.
+In some cases it might be acceptable to merge code to *development* to make a pre-release from it without including full automated tests and documentation.
+However this is a special case, because it blocks further releases from the *development* branch until the tests and docs are there.
 
 Branching model
 ~~~~~~~~~~~~~~~
 
 This project implements something like git flow.
 
-*TL;DR* branch off of *development* for new features, or *main* for minor bug
-fixes or doc improvements.
+*TL;DR* branch off of *development* for new features, or *main* for documentation improvements.
 
-We like to keep a clean history, so squash-rebase merges are preferred for the
-*development* or *main* branches.
+We like to keep a clean history, so squash-rebase merges are preferred for the *development* or *main* branches.
 
 Overview of branches
 ~~~~~~~~~~~~~~~~~~~~
@@ -95,8 +73,7 @@ Historic branches
 ^^^^^^^^^^^^^^^^^
 
 - **main** the primary branch containing released code and up to date docs.
-- **development** in progress and pre-released features that are expected to be
- included in a release when ready.
+- **development** in progress and pre-released features that are expected to be included in a release when ready.
 
 Working branches
 ^^^^^^^^^^^^^^^^
@@ -132,23 +109,9 @@ How to add a hot fix
 
 2. Create a pull request back to *main*, and one to *development*
 
-How to create pre-release
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. From the head of the *development* branch, create release commit that
- bumps the version in ``pyproject.toml`` and ``__version__.py``
- (there’s a test to ensure these are in sync).
-2. Create a release (and tag) on GitHub, following the existing
- convention for naming and release notes format, and the GitHub CI
- will do the rest.
-
 How to create release
 ~~~~~~~~~~~~~~~~~~~~~
 
-1. Create a branch off of *development* like **release/1.0.0** and add a
- commit to bump the version in ``pyproject.toml`` and
- ``__version__.py``.
-2. Merge it into both *main* and *development*
-3. Create a GitHub release from the head of main, following the existing
- convention for naming and release notes format, and the GitHub CI
- will do the rest.
+1. From the head of the *development* branch, create release commit that bumps the version in ``pyproject.toml`` and ``__version__.py`` (there’s a test to ensure these are in sync).
+2. Create a release (and tag) on GitHub, following the existing convention for naming and release notes format (use the *Generate release notes* button as a starting point), and the GitHub CI will do the rest.
+3. Unless it is a pre-release then the final step is to merge *development* into *main*.

.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Description of changes
+
+Replace this text with a description of the changes proposed in this PR, including the motivation for these changes and a reference to any related GitHub issue or discussion.
+
+## Pre-merge Checklist
+
+- [ ] New features (if any) are covered by new feature tests
+- [ ] New features (if any) are documented
+- [ ] `poe check` executed successfully
+- [ ] PR targets the *development* branch for code changes or *main* if only documentation is updated