Adopt scriv for CHANGELOG management (#53)

Closes #37

CHANGELOG.rst

@@ -0,0 +1,36 @@
+.. _changelog:
+
+---------
+Changelog
+---------
+
+.. note::
+
+   Until the Python API has stabilised, ``venvstacks`` is using
+   `ZeroVer <https://0ver.org/>`__ (starting from 0.1.0).
+
+   Refer to the :ref:`version-numbering` for additional details
+   on the way releases are versioned.
+
+
+Unreleased
+==========
+
+See the fragment files in the `changelog.d directory`_.
+
+.. _changelog.d directory: https://github.com/lmstudio-ai/venvstacks/tree/master/changelog.d
+
+
+.. scriv-insert-here
+
+.. _changelog-0.1.0rc1:
+
+0.1.0rc1 — 2024-10-29
+=====================
+
+Added
+-----
+
+- Initial export of `venvstacks` from Project Amphibian.
+
+- Adopted ``scriv`` for ``CHANGELOG`` management.

changelog.d/README.txt

@@ -0,0 +1 @@
+Unpublished CHANGELOG entries (managed via scriv)

changelog.d/ghrel_template.md.j2

@@ -0,0 +1,3 @@
+:arrow_right:  PyPI page: [ venvstacks {{version}}](https://pypi.org/project/venvstacks/{{version}}).
+
+{{body}}

ci-bootstrap-requirements.txt

@@ -111,6 +111,6 @@ typing-extensions==4.12.2 \
 unearth==0.17.2 \
     --hash=sha256:0b8a2afd3476f1ab6155fc579501ac47fffe43547d88a70e5a5b76a7fe6caa2c \
     --hash=sha256:4d21af1238a583835fca156322f7225382e718cdcc42d6278050a88e605c4ad5
-virtualenv==20.27.0 \
-    --hash=sha256:2ca56a68ed615b8fe4326d11a0dca5dfbe8fd68510fb6c6349163bed3c15f2b2 \
-    --hash=sha256:44a72c29cceb0ee08f300b314848c86e57bf8d1f13107a5e671fb9274138d655
+virtualenv==20.27.1 \
+    --hash=sha256:142c6be10212543b32c6c45d3d3893dff89112cc588b7d0879ae5a1ec03a47ba \
+    --hash=sha256:f11f1b8a29525562925f745563bfd48b189450f61fb34c4f9cc79dd5aa32a1f4

ci-constraints.txt

@@ -49,6 +49,9 @@ charset-normalizer==3.4.0 \
 click==8.1.7 \
     --hash=sha256:ae74fb96c20a0277a1d615f1e4d73c8414f5a98db8b799a7931d1582f3390c28 \
     --hash=sha256:ca9853ad459e787e2192211578cc907e7594e294c7ccc834310722b41b9ca6de
+click-log==0.4.0 \
+    --hash=sha256:3970f8570ac54491237bcdb3d8ab5e3eef6c057df29f8c3d1151a51a9c23b975 \
+    --hash=sha256:a43e394b528d52112af599f2fc9e4b7cf3c15f94e53581f74fa6867e68c91756
 colorama==0.4.6 \
     --hash=sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44 \
     --hash=sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6
@@ -229,6 +232,9 @@ ruff==0.7.1 \
     --hash=sha256:79d3af9dca4c56043e738a4d6dd1e9444b6d6c10598ac52d146e331eb155a8ad \
     --hash=sha256:9d8a41d4aa2dad1575adb98a82870cf5db5f76b2938cf2206c22c940034a36f4 \
     --hash=sha256:f38c41fcde1728736b4eb2b18850f6d1e3eedd9678c914dede554a70d5241307
+scriv==1.5.1 \
+    --hash=sha256:30ae9ff8d144f8e0cf394c4e1d379542f1b3823767642955b54ec40dc00b32b6 \
+    --hash=sha256:a3adc657733b4124fcb54527a5f3daab0d3c300de82d0fd2b9b297b243151b78
 shellingham==1.5.4 \
     --hash=sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686 \
     --hash=sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de
@@ -302,6 +308,6 @@ uv==0.4.21 \
     --hash=sha256:9dcddbb3b6e1662c6db41d63db539742450e2ce17d6c746329c016e3651bfb4a \
     --hash=sha256:a1a9a126ce48f0f0893891adb5a9749220425169092f3e4da1216168736ac16d \
     --hash=sha256:ba3e3b40cc1d5a980d36589775d6a7e4defa1b33e7e06423af0e395b8e4d9505
-virtualenv==20.27.0 \
-    --hash=sha256:2ca56a68ed615b8fe4326d11a0dca5dfbe8fd68510fb6c6349163bed3c15f2b2 \
-    --hash=sha256:44a72c29cceb0ee08f300b314848c86e57bf8d1f13107a5e671fb9274138d655
+virtualenv==20.27.1 \
+    --hash=sha256:142c6be10212543b32c6c45d3d3893dff89112cc588b7d0879ae5a1ec03a47ba \
+    --hash=sha256:f11f1b8a29525562925f745563bfd48b189450f61fb34c4f9cc79dd5aa32a1f4

docs/api/index.rst

@@ -1,5 +1,6 @@
+----------
 Python API
-==========
+----------
 
 .. warning::
 

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -48,6 +48,7 @@
 
 intersphinx_mapping = {
     "py": ("https://docs.python.org/3", None),
+    "packaging": ("https://packaging.python.org/en/latest/", None),
 }
 
 

docs/design.rst

@@ -1,5 +1,9 @@
+-----------------
 Design Discussion
-=================
+-----------------
+
+Project
+=======
 
 Why does ``venvstacks`` exist?
 ------------------------------
@@ -37,7 +41,7 @@ environments, it doesn't refer to being able combine ``sys.path``
 across multiple environments.
 
 Splitting environments into layers the way ``venvstacks`` does
-really doesn't align well with the way the ``conda`` dependency
+also doesn't align well with the way the ``conda`` dependency
 resolver works, so it ended up making more sense to design
 ``venvstacks`` to work with ``venv`` and ``pip``.
 
@@ -47,6 +51,10 @@ archives were eliminated from consideration as they lacked the ability
 to readily share the large common framework components that feature
 heavily in the Python AI ecosystem across different applications.
 
+
+Technical
+=========
+
 Why use ``python-build-standalone`` for the base runtimes?
 ----------------------------------------------------------
 

docs/development/index.rst

@@ -1,7 +1,12 @@
 .. _dev-guide:
 
+-----------
 Development
-===========
+-----------
+
+
+Getting Started
+===============
 
 (With thanks to pip's `Getting Started`_ guide for the general structure here!)
 
@@ -32,6 +37,29 @@ Given these tools, the default development environment can be set up
 and other commands executed as described below.
 
 
+Changelog Entries
+-----------------
+
+The ``venvstacks`` changelog is managed with :pypi:`scriv`.
+
+Entries are written in ``.rst`` format by default, so they
+can use semantic references to the rest of the documentation.
+However, ``.md`` fragments are entirely fine if internal
+semantic links aren't needed.
+
+All changes which may affect ``venvstacks`` users should be
+given a user facing changelog entry with ``scriv create``.
+
+Refer to the
+`"per-user" settings <https://scriv.readthedocs.io/en/1.5.1/configuration.html#per-user-git-settings>`__
+in the ``scriv`` documentation for details on how to customise the
+local behaviour of ``scriv create``.
+
+The project level ``scriv`` settings are stored in
+``pyproject.toml`` (but the project largely relies on the default
+settings)
+
+
 Running from the source tree
 ----------------------------
 
@@ -62,6 +90,22 @@ venvstacks can then be executed via the ``-m`` switch:
     │ publish        Publish layer archives for Python virtual environment stacks.    │
     ╰─────────────────────────────────────────────────────────────────────────────────╯
 
+Building Documentation
+----------------------
+
+pip's documentation is built using :pypi:`Sphinx`. The documentation is written
+in reStructuredText.
+
+To build it locally, run:
+
+.. code-block:: console
+
+    $ tox -e docs
+
+The built documentation can be found in the ``docs/_build`` folder.
+
+Automated Testing
+=================
 
 Code consistency checks
 -----------------------
@@ -95,7 +139,7 @@ All of these commands can be invoked via tox:
     ``# fmt: off/on`` and ``# fmt: skip`` comments may be used as needed
     when the autoformatter makes readability worse instead of better
     (for example, collapsing lists to a single line when they intentionally
-    cover multiple lines, or )
+    cover multiple lines, or breaking alignment of end-of-line comments).
 
 
 Running tests locally
@@ -183,19 +227,51 @@ closing and reopening the PR once the relevants fixes have been
 implemented.
 
 
-Building Documentation
+Release Management
+==================
+
+.. _version-numbering:
+
+Version Numbering
+-----------------
+
+Until the Python API has stabilised, ``venvstacks`` is using
+`ZeroVer <https://0ver.org/>`__ (starting from 0.1.0).
+
+The versioning scheme to be used after the leading zero is
+dropped has not yet been decided (see
+:external+packaging:ref:`versioning`
+for some of the options being considered).
+
+Except for when a release is being prepared, the nominal version on
+``main`` will have ``.dev0`` appended to indicate it is not a
+release build.
+
+Most releases are expected to be published directly without a prior
+release candidate build, but one may be used if it is deemed
+necessary (for example, ``0.1.0rc1`` was published in order to
+test the release pipeline prior to publishing ``0.1.0``).
+
+
+Preparing New Releases
 ----------------------
 
-pip's documentation is built using :pypi:`Sphinx`. The documentation is written
-in reStructuredText.
+Prior to release:
 
-To build it locally, run:
+* Update the version in ``pyproject.toml`` to remove the pre-release suffix
+* Run ``scriv collect`` to update ``CHANGELOG.rst``
+* Create a PR for the collected change log updates
+* Check the updated docs after the PR has been merged
 
-.. code-block:: console
+Release (requires ``pandoc``):
 
-    $ tox -e docs
+* Run ``scriv github-release --dry-run`` to check what would be published
+* Run ``scriv github-release`` to make the release tag
 
-The built documentation can be found in the ``docs/_build`` folder.
+After release:
+
+* Check the release GitHub Action has published to PyPI correctly
+* Bump the version in ``pyproject.toml`` and add a ``.dev0`` suffix
 
 .. _`Getting Started`: https://pip.pypa.io/en/stable/development/getting-started/
 .. _`open an issue`: https://github.com/lmstudio/venvstacks/issues/new?title=Trouble+with+development+environment

docs/glossary.rst

@@ -1,5 +1,6 @@
+----------------------------
 Essential Terms and Concepts
-============================
+----------------------------
 
 .. glossary::
 

docs/index.rst

@@ -14,3 +14,4 @@ Welcome to ``venvstacks``'s documentation!
    design
    api/index
    development/index
+   changelog

docs/overview.rst

@@ -1,5 +1,6 @@
+----------------------------------
 Layered Virtual Environment Stacks
-==================================
+----------------------------------
 
 ``venvstacks`` uses Python's ``sitecustomize.py`` environment setup feature
 to chain together three layers of Python virtual environments:
@@ -14,7 +15,7 @@ and the framework layers to share dependencies installed in the runtime layers.
 
 
 Installing
-----------
+==========
 
 ``venvstacks`` is available from the :pypi:`Python Package Index <venvstacks>`,
 and can be installed with :pypi:`pipx` (or similar tools):
@@ -59,6 +60,9 @@ The command line help also provides additional usage information:
    :issue:`supported in a future release <26>`.
 
 
+Working with environment stacks
+===============================
+
 Defining environment stacks
 ---------------------------
 
@@ -178,7 +182,7 @@ but the details related specifically to the published archive (such as its size
 contents hash) are necessarily omitted.
 
 Contributing to ``venvstacks`` development
-------------------------------------------
+==========================================
 
 ``venvstacks`` is MIT Licensed and `developed on GitHub <https://github.com/lmstudio-ai/venvstacks>`__.
 

docs/requirements.txt

@@ -12,6 +12,7 @@ certifi==2024.8.30
 chardet==5.2.0
 charset-normalizer==3.4.0
 click==8.1.7
+click-log==0.4.0
 colorama==0.4.6
 coverage[toml]==7.6.4
 dep-logic==0.4.9
@@ -51,6 +52,7 @@ requests==2.32.3
 resolvelib==1.0.1
 rich==13.9.3
 ruff==0.7.1
+scriv[toml]==1.5.1
 shellingham==1.5.4
 sniffio==1.3.1
 snowballstemmer==2.2.0
@@ -74,5 +76,5 @@ typing-extensions==4.12.2
 unearth==0.17.2
 urllib3==2.2.3
 uv==0.4.21
-virtualenv==20.27.0
+virtualenv==20.27.1
 .  # this package