Skip to content

Commit

Permalink
docs/development: Summarise important points experienced devs need to…
Browse files Browse the repository at this point in the history
… know

Experienced developers' eyes tend to quickly glaze over when reading
developer documentation that starts with things like "how to clone a repo
from GitHub." This new section at the top briefly covers key points
specific to this project to help developers already familiar with Python
development and GitHub PRs.

This is based on my experience submitting my first PR to this project; it's
what I wish I'd had to save me some time and conversation in the PR.
  • Loading branch information
0cjs committed Jan 24, 2024
1 parent 84f5406 commit bd85c68
Show file tree
Hide file tree
Showing 2 changed files with 30 additions and 0 deletions.
1 change: 1 addition & 0 deletions docs/changelog/3197.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Development: summarise important points experienced developers need to know - by :user:`0cjs`.
29 changes: 29 additions & 0 deletions docs/development.rst
Original file line number Diff line number Diff line change
@@ -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
---------------

Expand Down

0 comments on commit bd85c68

Please sign in to comment.