From 2754213b760fa4ba845bddda3ac4c0ec34c39e4b Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sun, 20 Sep 2020 19:39:57 +0200 Subject: Fix command block in dev guide to `shell-session` This type is more appropriate for snippets containing shell commands with leading prompts followed by their output. `bash` syntax used earlier treats everything as a raw shell script contents highlighting words like `for`. --- docs/developer-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/developer-guide.rst') diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index e84cd640..efbf1b7c 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -84,7 +84,7 @@ case two fragments should be added. It is not necessary to make a separate documentation fragment for documentation changes accompanying the relevant code changes. See the following for an example news fragment: -.. code-block:: bash +.. code-block:: shell-session $ cat changelog.d/1288.change.rst Add support for maintainer in PKG-INFO -- cgit v1.2.1 From 0d6920524ed2395e1cab7e7141c58423d94a424f Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Sun, 20 Sep 2020 21:14:59 +0200 Subject: =?UTF-8?q?=F0=9F=93=9D=20Add=20an=20illustrative=20explanation=20?= =?UTF-8?q?of=20change=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This change places a `README.rst` document under `changelog.d/` dir in order for GitHub to render it when users navigate to this location via the web UI. It also includes that into the dev guide in Sphinx docs. --- docs/developer-guide.rst | 35 ++++++++--------------------------- 1 file changed, 8 insertions(+), 27 deletions(-) (limited to 'docs/developer-guide.rst') diff --git a/docs/developer-guide.rst b/docs/developer-guide.rst index efbf1b7c..d2366931 100644 --- a/docs/developer-guide.rst +++ b/docs/developer-guide.rst @@ -61,33 +61,14 @@ jump to the in-depth discussion about any subject referenced. Making a pull request --------------------- -When making a pull request, please include a short summary of the changes -and a reference to any issue tickets that the PR is intended to solve. -All PRs with code changes should include tests. All changes should include a -changelog entry. - -``setuptools`` uses `towncrier `_ -for changelog management, so when making a PR, please add a news fragment in the -``changelog.d/`` folder. Changelog files are written in reStructuredText and -should be a 1 or 2 sentence description of the substantive changes in the PR. -They should be named ``..rst``, where the categories are: - -- ``change``: Any backwards compatible code change -- ``breaking``: Any backwards-compatibility breaking change -- ``doc``: A change to the documentation -- ``misc``: Changes internal to the repo like CI, test and build changes -- ``deprecation``: For deprecations of an existing feature or behavior - -A pull request may have more than one of these components, for example a code -change may introduce a new feature that deprecates an old feature, in which -case two fragments should be added. It is not necessary to make a separate -documentation fragment for documentation changes accompanying the relevant -code changes. See the following for an example news fragment: - -.. code-block:: shell-session - - $ cat changelog.d/1288.change.rst - Add support for maintainer in PKG-INFO +When making a pull request, please +:ref:`include a short summary of the changes ` and a reference to any issue tickets that the PR is +intended to solve. +All PRs with code changes should include tests. All changes should +include a changelog entry. + +.. include:: ../changelog.d/README.rst ------------------- Auto-Merge Requests -- cgit v1.2.1