Merge pull request #3989 from jobh/release-rst-example

Sample RELEASE.rst

Author: Zac-HD

CONTRIBUTING.rst

@@ -10,7 +10,8 @@ Just tell me how to make a pull request
 
 1. Make your change and ensure it has adequate tests
 2. Create ``hypothesis-python/RELEASE.rst`` with ``RELEASE_TYPE: patch``
-   for small bugfixes, or ``minor`` for new features.  See recent PRs for examples.
+   for small bugfixes, or ``minor`` for new features.  See ``RELEASE-sample.rst``
+   as an example.
 3. Add yourself to the list in ``AUTHORS.rst`` and open a PR!
 
 For more detail, read on; for even more, continue to the ``guides/`` directory!

hypothesis-python/RELEASE-sample.rst

@@ -0,0 +1,36 @@
+RELEASE_TYPE: patch
+
+This patch improves import-detection in :doc:`the Ghostwriter <ghostwriter>`
+(:issue:`3884`), particularly for :func:`~hypothesis.strategies.from_type`
+and strategies from ``hypothesis.extra.*``.
+
+Thanks to <contributor's name or handle> for this <contribution/fix/feature>!
+
+---
+
+In the example above, "patch" on the first line should be replaced by
+"minor" if changes are visible in the public API, or "major" if there are
+breaking changes.  Note that only maintainers should ever make a major
+release.
+
+The remaining lines are the actual changelog text for this release,
+which should:
+
+- concisely describe what changed _in the public API_, and why.
+  Internal-only changes can be documented as e.g. "This release improves
+  an internal invariant." (the complete changelog for version 6.99.11)
+- use ``double backticks`` for verbatim code,
+- use Sphinx cross-references to any functions or classes mentioned:
+  - :pypi:`package` for links to external packages,
+  - :func:`package.function` for link to functions, where the link text will
+    be ``package.function``, or :func:`~package.function` to show ``function``,
+  - :class:`package.class` for link to classes (abbreviated as above),
+  - :issue:`issue-number` for referencing issues,
+  - :doc:`link text <chapter#anchor>` for documentation references
+    (``https://hypothesis.readthedocs.io/en/latest/<chapter>.html#<anchor>``)
+- finish with a note of thanks from the maintainers. If this is your first
+  contribution, don't forget to add yourself to AUTHORS.rst!
+
+After the PR is merged, the contents of this file (except the first line)
+are automatically added to ``docs/changes.rst``. More examples can be found
+in that file.

hypothesis-python/RELEASE.rst

@@ -0,0 +1,3 @@
+RELEASE_TYPE: patch
+
+Internal developer documentation, no user-visible changes.

tooling/src/hypothesistooling/projects/hypothesispython.py

@@ -32,6 +32,7 @@
 DOMAINS_LIST = PYTHON_SRC / "hypothesis" / "vendor" / "tlds-alpha-by-domain.txt"
 
 RELEASE_FILE = HYPOTHESIS_PYTHON / "RELEASE.rst"
+RELEASE_SAMPLE_FILE = HYPOTHESIS_PYTHON / "RELEASE-sample.rst"
 
 assert PYTHON_SRC.exists()
 
@@ -52,6 +53,10 @@ def has_release():
     return RELEASE_FILE.exists()
 
 
+def has_release_sample():
+    return RELEASE_SAMPLE_FILE.exists()
+
+
 def parse_release_file():
     return rm.parse_release_file(RELEASE_FILE)
 

whole_repo_tests/test_release_files.py

@@ -20,7 +20,12 @@ def test_release_file_exists_and_is_valid(project):
     if project.has_source_changes():
         assert project.has_release(), (
             "There are source changes but no RELEASE.rst. Please create "
-            "one to describe your changes."
+            "one to describe your changes. An example can be found in "
+            "RELEASE-sample.rst."
+        )
+        assert project.has_release_sample(), (
+            "The RELEASE-sample.rst file is missing. Please copy it "
+            "to RELEASE.rst, rather than moving it."
         )
         rm.parse_release_file(project.RELEASE_FILE)
 

whole_repo_tests/test_rst_is_valid.py

@@ -23,7 +23,8 @@ def is_sphinx(f):
 ALL_RST = [
     f
     for f in tools.all_files()
-    if os.path.basename(f) != "RELEASE.rst" and f.endswith(".rst")
+    if os.path.basename(f) not in ["RELEASE.rst", "RELEASE-sample.rst"]
+    and f.endswith(".rst")
 ]