.. _program_listing_file_RELEASING.md:

Program Listing for File RELEASING.md
=====================================

|exhale_lsh| :ref:`Return to documentation for file <file_RELEASING.md>` (``RELEASING.md``)

.. |exhale_lsh| unicode:: U+021B0 .. UPWARDS ARROW WITH TIP LEFTWARDS

.. code-block:: markdown

   # Releasing
   
   ## Python package on PyPI
   
   One-time setup (project owner):
   
   1. Create the `fields2cover` project on https://pypi.org and https://test.pypi.org
      (first upload creates it; alternatively register a *pending publisher*).
   2. On both, add a **Trusted Publisher**: owner `Fields2Cover`, repository
      `Fields2Cover`, workflow `pypi.yml`, environment `pypi` (resp. `testpypi`).
   3. In the GitHub repository create the environments `pypi` and `testpypi`
      (Settings → Environments). Optionally require reviewers for `pypi`.
   
   Per release:
   
   1. Make sure `CHANGELOG.md` has an `## [Unreleased]` section describing the
      release; it becomes the release notes.
   2. Optional dry run: *Actions → PyPI → Run workflow → target: testpypi*, then
      `pip install --index-url https://test.pypi.org/simple/ fields2cover`.
   3. From an up-to-date, clean `main` run `./release.sh X.Y.Z` (needs the
      GitHub CLI, `gh auth login`). It bumps the version in `CMakeLists.txt` and
      `package.xml`, turns `[Unreleased]` into the `[X.Y.Z]` section, shows the
      diff and — after confirmation — commits, pushes and publishes the GitHub
      release `vX.Y.Z`. The same steps can be done by hand; publishing the
      release is what triggers the upload.
   4. The `PyPI` workflow builds the sdist, installs it in a clean container and
      uploads it. If the `pypi` environment requires reviewers, approve the
      deployment in the running workflow. The workflow refuses to publish when
      `package.xml` and `CMakeLists.txt` disagree or when the tag does not match
      `VERSION` in `CMakeLists.txt`.
   5. A published PyPI release cannot be replaced or re-uploaded. If a release
      turns out to be broken, release a patch version the same way.