Merge pull request #220 from lsst/tickets/DM-40567

DM-40567: Add scriv to FastAPI and PyPI templates

project_templates/fastapi_safir_app/example/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Change log
+
+example is versioned with [semver](https://semver.org/).
+Dependencies are updated to the latest available version during each release, and aren't noted here.
+
+Find changes for the upcoming release in the project's [changelog.d directory](https://github.com/lsst-sqre/example/tree/main/changelog.d/).
+
+<!-- scriv-insert-here -->

project_templates/fastapi_safir_app/example/changelog.d/_template.md.jinja

@@ -0,0 +1,7 @@
+<!-- Delete the sections that don't apply -->
+{%- for cat in config.categories %}
+
+### {{ cat }}
+
+-
+{%- endfor %}

project_templates/fastapi_safir_app/example/pyproject.toml

@@ -207,3 +207,16 @@ classmethod-decorators = [
 
 [tool.ruff.pydocstyle]
 convention = "numpy"
+
+[tool.scriv]
+categories = [
+    "Backwards-incompatible changes",
+    "New features",
+    "Bug fixes",
+    "Other changes",
+]
+entry_title_template = "{{ version }} ({{ date.strftime('%Y-%m-%d') }})"
+format = "md"
+md_header_level = "2"
+new_fragment_template = "file:changelog.d/_template.md.jinja"
+skip_fragments = "_template.md.jinja"

project_templates/fastapi_safir_app/example/requirements/dev.in

@@ -9,6 +9,7 @@
 
 -c main.txt
 
+# Testing
 asgi-lifespan
 coverage[toml]
 httpx
@@ -18,3 +19,6 @@ pydantic
 pytest
 pytest-asyncio
 pytest-cov
+
+# Documentation
+scriv

project_templates/fastapi_safir_app/{{cookiecutter.name}}/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Change log
+
+{{cookiecutter.name}} is versioned with [semver](https://semver.org/).
+Dependencies are updated to the latest available version during each release, and aren't noted here.
+
+Find changes for the upcoming release in the project's [changelog.d directory](https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.name}}/tree/main/changelog.d/).
+
+<!-- scriv-insert-here -->

project_templates/fastapi_safir_app/{{cookiecutter.name}}/changelog.d/_template.md.jinja

@@ -0,0 +1,7 @@
+<!-- Delete the sections that don't apply -->
+{{ "{%- for cat in config.categories %}" }}
+
+### {{ "{{ cat }}" }}
+
+-
+{{ "{%- endfor %}" }}

project_templates/fastapi_safir_app/{{cookiecutter.name}}/pyproject.toml

@@ -207,3 +207,16 @@ classmethod-decorators = [
 
 [tool.ruff.pydocstyle]
 convention = "numpy"
+
+[tool.scriv]
+categories = [
+    "Backwards-incompatible changes",
+    "New features",
+    "Bug fixes",
+    "Other changes",
+]
+entry_title_template = "{{ "{{ version }} ({{ date.strftime('%Y-%m-%d') }})" }}"
+format = "md"
+md_header_level = "2"
+new_fragment_template = "file:changelog.d/_template.md.jinja"
+skip_fragments = "_template.md.jinja"

project_templates/fastapi_safir_app/{{cookiecutter.name}}/requirements/dev.in

@@ -9,6 +9,7 @@
 
 -c main.txt
 
+# Testing
 asgi-lifespan
 coverage[toml]
 httpx
@@ -18,3 +19,6 @@ pydantic
 pytest
 pytest-asyncio
 pytest-cov
+
+# Documentation
+scriv

project_templates/square_pypi_package/example/CHANGELOG.md

@@ -1,7 +1,7 @@
 # Change log
 
-<!-- Format for headings: 1.2.3 (YYYY-MM-DD) -->
+example is versioned with [semver](https://semver.org/).
 
-## Unreleased
+Find changes for the upcoming release in the project's [changelog.d directory](https://github.com/lsst-sqre/example/tree/main/changelog.d/).
 
-- First release of example
+<!-- scriv-insert-here -->

project_templates/square_pypi_package/example/changelog.d/_template.md.jinja

@@ -0,0 +1,7 @@
+<!-- Delete the sections that don't apply -->
+{%- for cat in config.categories %}
+
+### {{ cat }}
+
+-
+{%- endfor %}

project_templates/square_pypi_package/example/docs/_rst_epilog.rst

@@ -1,6 +1,7 @@
-
+.. _Click: https://click.palletsprojects.com/
 .. _mypy: http://www.mypy-lang.org
 .. _pre-commit: https://pre-commit.com
 .. _pytest: https://docs.pytest.org/en/latest/
+.. _scriv: https://scriv.readthedocs.io/en/stable/
+.. _semver: https://semver.org/
 .. _tox: https://tox.wiki/en/latest/
-.. _Click: https://click.palletsprojects.com/

project_templates/square_pypi_package/example/docs/dev/development.rst

@@ -101,30 +101,29 @@ The built documentation is located in the :file:`docs/_build/html` directory.
 Updating the change log
 =======================
 
-Each pull request should update the change log (:file:`CHANGELOG.md`).
-Add a description of new features and fixes as list items under a section at the top of the change log called "Unreleased:"
+example uses scriv_ to maintain its change log.
 
-.. code-block:: md
+When preparing a pull request, run :command:`scriv create`.
+This will create a change log fragment in :file:`changelog.d`.
+Edit that fragment, removing the sections that do not apply and adding entries fo this pull request.
+You can pass the ``--edit`` flag to :command:`scriv create` to open the created fragment automatically in an editor.
 
-   ## Unreleased
+Change log entries use the following sections:
 
-   - Description of the feature or fix.
+.. rst-class:: compact
 
-If the next version is known (because example's main branch is being prepared for a new major or minor version), the section may contain that version information:
+- **Backward-incompatible changes**
+- **New features**
+- **Bug fixes**
+- **Other changes** (for minor, patch-level changes that are not bug fixes, such as logging formatting changes or updates to the documentation)
 
-.. code-block:: md
+These entries will eventually be cut and pasted into the release description for the next release, so the Markdown for the change descriptions should be compatible with GitHub's Markdown conventions for the release description.
+Specifically:
 
-   ## X.Y.0 (unreleased)
-
-   - Description of the feature or fix.
-
-If the exact version and release date is known (:doc:`because a release is being prepared <release>`), the section header is formatted as:
-
-.. code-block:: md
-
-   ## X.Y.0 (YYYY-MM-DD)
-
-   - Description of the feature or fix.
+- Each bullet point should be entirely on one line, even if it contains multiple sentences.
+  This is an exception to the normal documentation convention of a newline after each sentence.
+  Unfortunately, GitHub interprets those newlines as hard line breaks, so they would result in an ugly release description.
+- Avoid using too much complex markup, such as nested bullet lists, since the formatting in the GitHub release description may not be what you expect and manually editing it is tedious.
 
 .. _style-guide:
 

project_templates/square_pypi_package/example/docs/dev/release.rst

@@ -26,11 +26,28 @@ Release tags are semantic version identifiers following the :pep:`440` specifica
 1. Change log and documentation
 -------------------------------
 
-Each PR should include updates to the change log.
-If the change log or documentation needs additional updates, now is the time to make those changes through the regular branch-and-PR development method against the ``main`` branch.
+Change log messages for each release are accumulated using scriv_.
+See :ref:`dev-change-log` in the *Developer guide* for more details.
 
-In particular, replace the "Unreleased" section headline with the semantic version and date.
-See :ref:`dev-change-log` in the *Developer guide* for details.
+When it comes time to make the release, there should be a collection of change log fragments in :file:`changelog.d`.
+Those fragments will make up the change log for the new release.
+
+Review those fragments to determine the version number of the next release.
+Safir follows semver_, so follow its rules to pick the next version:
+
+.. rst-class:: compact
+
+- If there are any backward-incompatible changes, incremeent the major version number and set the other numbers to 0.
+- If there are any new features, increment the minor version number and set the patch version to 0.
+- Otherwise, increment the patch version number.
+
+Then, run ``scriv collect --version <version>`` specifying the version number you decided on.
+This will delete the fragment files and collect them into :file:`CHANGELOG.md` under an entry for the new release.
+Review that entry and edit it as needed (proofread, change the order to put more important things first, etc.).
+scriv will put blank lines between entries from different files.
+You may wish to remove those blank lines to ensure consistent formatting by various Markdown parsers.
+
+Finally, create a PR from those changes and merge it before continuing with the release process.
 
 2. GitHub release and tag
 -------------------------
@@ -75,7 +92,7 @@ If the release branch doesn't already exist, check out the latest patch for that
 Developing on a release branch
 ------------------------------
 
-Once a release branch exists, it becomes the "master" branch for patches of that major-minor version.
+Once a release branch exists, it becomes the "main" branch for patches of that major-minor version.
 Pull requests should be based on, and merged into, the release branch.
 
 If the development on the release branch is a backport of commits on the ``main`` branch, use ``git cherry-pick`` to copy those commits into a new pull request against the release branch.

project_templates/square_pypi_package/example/pyproject.toml

@@ -34,6 +34,7 @@ dev = [
     "mypy",
     # Documentation
     "documenteer[guide]<1",
+    "scriv",
 ]
 
 [project.urls]
@@ -234,3 +235,16 @@ classmethod-decorators = [
 
 [tool.ruff.pydocstyle]
 convention = "numpy"
+
+[tool.scriv]
+categories = [
+    "Backwards-incompatible changes",
+    "New features",
+    "Bug fixes",
+    "Other changes",
+]
+entry_title_template = "{{ version }} ({{ date.strftime('%Y-%m-%d') }})"
+format = "md"
+md_header_level = "2"
+new_fragment_template = "file:changelog.d/_template.md.jinja"
+skip_fragments = "_template.md.jinja"

project_templates/square_pypi_package/{{cookiecutter.name}}/CHANGELOG.md

@@ -1,7 +1,7 @@
 # Change log
 
-<!-- Format for headings: 1.2.3 (YYYY-MM-DD) -->
+{{cookiecutter.name}} is versioned with [semver](https://semver.org/).
 
-## Unreleased
+Find changes for the upcoming release in the project's [changelog.d directory](https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.name}}/tree/main/changelog.d/).
 
-- First release of {{cookiecutter.name}}
+<!-- scriv-insert-here -->

project_templates/square_pypi_package/{{cookiecutter.name}}/changelog.d/_template.md.jinja

@@ -0,0 +1,7 @@
+<!-- Delete the sections that don't apply -->
+{{ "{%- for cat in config.categories %}" }}
+
+### {{ "{{ cat }}" }}
+
+-
+{{ "{%- endfor %}" }}

project_templates/square_pypi_package/{{cookiecutter.name}}/docs/_rst_epilog.rst

@@ -1,6 +1,7 @@
-
+.. _Click: https://click.palletsprojects.com/
 .. _mypy: http://www.mypy-lang.org
 .. _pre-commit: https://pre-commit.com
 .. _pytest: https://docs.pytest.org/en/latest/
+.. _scriv: https://scriv.readthedocs.io/en/stable/
+.. _semver: https://semver.org/
 .. _tox: https://tox.wiki/en/latest/
-.. _Click: https://click.palletsprojects.com/

project_templates/square_pypi_package/{{cookiecutter.name}}/docs/dev/development.rst

@@ -101,30 +101,29 @@ The built documentation is located in the :file:`docs/_build/html` directory.
 Updating the change log
 =======================
 
-Each pull request should update the change log (:file:`CHANGELOG.md`).
-Add a description of new features and fixes as list items under a section at the top of the change log called "Unreleased:"
+{{cookiecutter.name}} uses scriv_ to maintain its change log.
 
-.. code-block:: md
+When preparing a pull request, run :command:`scriv create`.
+This will create a change log fragment in :file:`changelog.d`.
+Edit that fragment, removing the sections that do not apply and adding entries fo this pull request.
+You can pass the ``--edit`` flag to :command:`scriv create` to open the created fragment automatically in an editor.
 
-   ## Unreleased
+Change log entries use the following sections:
 
-   - Description of the feature or fix.
+.. rst-class:: compact
 
-If the next version is known (because {{cookiecutter.name}}'s main branch is being prepared for a new major or minor version), the section may contain that version information:
+- **Backward-incompatible changes**
+- **New features**
+- **Bug fixes**
+- **Other changes** (for minor, patch-level changes that are not bug fixes, such as logging formatting changes or updates to the documentation)
 
-.. code-block:: md
+These entries will eventually be cut and pasted into the release description for the next release, so the Markdown for the change descriptions should be compatible with GitHub's Markdown conventions for the release description.
+Specifically:
 
-   ## X.Y.0 (unreleased)
-
-   - Description of the feature or fix.
-
-If the exact version and release date is known (:doc:`because a release is being prepared <release>`), the section header is formatted as:
-
-.. code-block:: md
-
-   ## X.Y.0 (YYYY-MM-DD)
-
-   - Description of the feature or fix.
+- Each bullet point should be entirely on one line, even if it contains multiple sentences.
+  This is an exception to the normal documentation convention of a newline after each sentence.
+  Unfortunately, GitHub interprets those newlines as hard line breaks, so they would result in an ugly release description.
+- Avoid using too much complex markup, such as nested bullet lists, since the formatting in the GitHub release description may not be what you expect and manually editing it is tedious.
 
 .. _style-guide:
 

project_templates/square_pypi_package/{{cookiecutter.name}}/docs/dev/release.rst

@@ -26,11 +26,28 @@ Release tags are semantic version identifiers following the :pep:`440` specifica
 1. Change log and documentation
 -------------------------------
 
-Each PR should include updates to the change log.
-If the change log or documentation needs additional updates, now is the time to make those changes through the regular branch-and-PR development method against the ``main`` branch.
+Change log messages for each release are accumulated using scriv_.
+See :ref:`dev-change-log` in the *Developer guide* for more details.
 
-In particular, replace the "Unreleased" section headline with the semantic version and date.
-See :ref:`dev-change-log` in the *Developer guide* for details.
+When it comes time to make the release, there should be a collection of change log fragments in :file:`changelog.d`.
+Those fragments will make up the change log for the new release.
+
+Review those fragments to determine the version number of the next release.
+Safir follows semver_, so follow its rules to pick the next version:
+
+.. rst-class:: compact
+
+- If there are any backward-incompatible changes, incremeent the major version number and set the other numbers to 0.
+- If there are any new features, increment the minor version number and set the patch version to 0.
+- Otherwise, increment the patch version number.
+
+Then, run ``scriv collect --version <version>`` specifying the version number you decided on.
+This will delete the fragment files and collect them into :file:`CHANGELOG.md` under an entry for the new release.
+Review that entry and edit it as needed (proofread, change the order to put more important things first, etc.).
+scriv will put blank lines between entries from different files.
+You may wish to remove those blank lines to ensure consistent formatting by various Markdown parsers.
+
+Finally, create a PR from those changes and merge it before continuing with the release process.
 
 2. GitHub release and tag
 -------------------------
@@ -75,7 +92,7 @@ If the release branch doesn't already exist, check out the latest patch for that
 Developing on a release branch
 ------------------------------
 
-Once a release branch exists, it becomes the "master" branch for patches of that major-minor version.
+Once a release branch exists, it becomes the "main" branch for patches of that major-minor version.
 Pull requests should be based on, and merged into, the release branch.
 
 If the development on the release branch is a backport of commits on the ``main`` branch, use ``git cherry-pick`` to copy those commits into a new pull request against the release branch.

project_templates/square_pypi_package/{{cookiecutter.name}}/pyproject.toml

@@ -34,6 +34,7 @@ dev = [
     "mypy",
     # Documentation
     "documenteer[guide]<1",
+    "scriv",
 ]
 
 [project.urls]
@@ -234,3 +235,16 @@ classmethod-decorators = [
 
 [tool.ruff.pydocstyle]
 convention = "numpy"
+
+[tool.scriv]
+categories = [
+    "Backwards-incompatible changes",
+    "New features",
+    "Bug fixes",
+    "Other changes",
+]
+entry_title_template = "{{ "{{ version }} ({{ date.strftime('%Y-%m-%d') }})" }}"
+format = "md"
+md_header_level = "2"
+new_fragment_template = "file:changelog.d/_template.md.jinja"
+skip_fragments = "_template.md.jinja"