docs/development: Summarise important points experienced devs need to…

… know (#3197)

docs/changelog/3197.doc.rst

@@ -0,0 +1 @@
+Development: summarise important points experienced developers need to know - by :user:`0cjs`.

docs/development.rst

@@ -1,6 +1,35 @@
 Development
 ===========
 
+Key points
+----------
+
+If you're already experienced with submitting GitHub PRs to open-source Python projects, the following are the key
+points you need to know about this project. (If you're not, you should carefully read all the documentation after this
+section. This section contains only highlights; it's not a substitute for reading this entire file.)
+
+- Check the `style guide <#style-guide>`_ below. Particularly note that lines should be wrapped at 120 characters, not
+  the PEP-8 standard of 79. The linter will not catch short lines, but most other formatting details should be caught by
+  the tests and linting below.
+- Documentation is in `RST <https://docutils.sourceforge.io/docs/user/rst/quickref.html>`_ format; beware the
+  differences from GitHub Markdown. The tox ``docs`` and ``fix`` targets will catch only some RST errors; documentation
+  changes *must* be checked visually (see below).
+- All PRs require a changelog entry. This should reference an issue if it closes that issue, otherwise reference the PR.
+  Create one or more (if there's more than one issue) ``docs/changelog/####.{feature,bugfix,doc,removal,misc}.rst`` per
+  the `changelog entry <#changelog-entries>`_ section below.
+- GitHub Actions will do a full set of `tests and checks <#automated-testing>`_ when the PR is submitted. For local
+  testing you'll need to install your own "top-level" tox; (using `pipx`_ or similar is fine)
+  and the following targets.
+
+  - :samp:`tox -e py [-- {pytest-arg ...}]`  to `test code changes <#running-tests>`_. This will skip tests for which
+    you are missing dependencies, but those tests will still be run by GitHub Actions.
+  - ``tox -e type`` to typecheck changes. (All new code should have type annotations.)
+  - ``tox -e docs`` to build documentation changes and update the changelog, followed by viewing (with a browser) the
+    generated HTML files under :file:`.tox/docs_out/`. The required changelog entry can be viewed at the "Release
+    History" link at the left.
+  - ``tox -e fix`` to lint code, documentation and any other changes to the repo.
+
+
 Getting started
 ---------------
 
@@ -182,7 +211,8 @@ Contents of a changelog entry
 
 The content of this file is reStructuredText formatted text that will be used as the content of the changelog entry.
 You do not need to reference the issue or PR numbers here as towncrier will automatically add a reference to all of the
-affected issues when rendering the changelog.
+affected issues when rendering the changelog. You may append ``- by :user:USERNAME``, with a GitHub username in
+backticks, if you wish.
 
 In order to maintain a consistent style in the ``changelog.rst`` file, it is preferred to keep the entries to the
 point, in sentence case, shorter than 120 characters and in an imperative tone -- an entry should complete the sentence
@@ -191,6 +221,14 @@ by a blank line separating it from a description of the feature/change in one or
 characters. Remember that a changelog entry is meant for end users and should only contain details relevant to an end
 user.
 
+An example of ``docs/changelog/####.bugfix.rst`` contents is:
+
+.. code-block::
+
+    Instead of raising ``UnicodeDecodeError`` when command output includes non-utf-8 bytes, ``tox`` will now use
+    ``surrogateescape`` error handling to convert the unrecognized bytes to escape sequences according to :pep:`383`
+    - by :user:`masenf`
+
 
 Becoming a maintainer
 ~~~~~~~~~~~~~~~~~~~~~