[docs] Document release publishing workflow (#73)

docs/internals/index.rst

@@ -9,3 +9,4 @@ step.
    :maxdepth: 1
 
    architecture
+   release-publishing

docs/internals/release-publishing.rst

@@ -0,0 +1,157 @@
+Release and Publishing Workflow
+===============================
+
+This guide is for maintainers preparing a Fast Forward DevTools release. It
+documents the current manual release flow and the publishing surfaces affected
+by a merge or tag. It does not add release automation.
+
+Release Surfaces
+----------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Surface
+     - Purpose
+     - Current behavior
+   * - GitHub ``main``
+     - Integration branch for accepted source and documentation changes.
+     - Pull requests merge into ``main`` after required checks pass.
+   * - Git tags
+     - Immutable release markers consumed by Composer and maintainers.
+     - Created manually when maintainers decide to publish a release.
+   * - Packagist
+     - Composer package discovery for ``fast-forward/dev-tools``.
+     - Reads repository tags and metadata for installable versions.
+   * - GitHub Pages
+     - Published reports, generated docs, and coverage pages.
+     - Updated by the reports workflow after changes land on ``main``.
+   * - GitHub Wiki
+     - Markdown documentation generated by ``composer dev-tools wiki``.
+     - Updated by the wiki workflow after changes land on ``main``.
+   * - GitHub Releases
+     - Human-facing release notes and changelog summary.
+     - Created manually when a tagged version should be announced.
+
+Versioning and Branch Flow
+--------------------------
+
+Use pull requests for all release-bound changes. The release candidate should
+land on ``main`` before any tag is created.
+
+The expected flow is:
+
+1. merge feature, bug fix, and documentation pull requests into ``main``;
+2. run the release verification checklist against the current ``main``;
+3. prepare changelog or release notes from merged work;
+4. create a version tag from the verified ``main`` commit;
+5. publish the GitHub release notes for that tag;
+6. confirm Packagist, reports, and wiki publication.
+
+Do not retag an existing published version. If a release needs correction,
+create a follow-up commit and publish a new version tag.
+
+Pre-Release Verification
+------------------------
+
+Run the full project gate before tagging:
+
+.. code-block:: bash
+
+    composer install
+    composer dev-tools
+
+For documentation-heavy releases, also verify the generated reports and wiki
+commands directly:
+
+.. code-block:: bash
+
+    composer dev-tools reports
+    composer dev-tools wiki
+
+Before creating the tag, check the repository state:
+
+.. code-block:: bash
+
+    git status --short
+    git log --oneline origin/main..HEAD
+
+The working tree should be clean, and the release commit should already be on
+``main``.
+
+Tagging and GitHub Release Notes
+--------------------------------
+
+Create the tag from the verified ``main`` commit:
+
+.. code-block:: bash
+
+    git switch main
+    git pull --ff-only
+    git tag <version>
+    git push origin <version>
+
+Use the GitHub release page for the pushed tag to publish release notes. The
+notes SHOULD include:
+
+- user-facing changes;
+- breaking changes or migration notes;
+- new or changed commands;
+- documentation and workflow changes that affect consumer repositories;
+- verification performed before the release.
+
+Packagist Publication
+---------------------
+
+Packagist uses the Git repository metadata for
+`fast-forward/dev-tools <https://packagist.org/packages/fast-forward/dev-tools>`_.
+After pushing a tag, confirm the version appears on Packagist and that Composer
+can resolve it from a clean consumer project.
+
+.. code-block:: bash
+
+    composer show fast-forward/dev-tools --all
+
+If Packagist does not show the version, inspect the package webhook or trigger a
+manual update from the Packagist package page.
+
+Reports and Wiki Publication
+----------------------------
+
+Reports and wiki publication are tied to ``main`` workflows, not to the tag
+itself:
+
+- the reports workflow publishes generated reports to GitHub Pages after
+  changes land on ``main``;
+- the wiki workflow promotes generated wiki content after changes land on
+  ``main``;
+- pull request previews remain review artifacts and should not be treated as
+  final release output.
+
+When a release contains documentation changes, validate the final Pages and wiki
+output after the merge to ``main`` and before announcing the release broadly.
+
+Post-Release Validation
+-----------------------
+
+After the tag and release notes are published:
+
+1. confirm the tag exists on GitHub;
+2. confirm the version appears on Packagist;
+3. install the tagged version in a temporary consumer project;
+4. verify GitHub Pages reports reflect the release commit;
+5. verify the GitHub Wiki reflects the release commit;
+6. check that no release pull request preview artifacts are left active by
+   mistake;
+7. open follow-up issues for any release automation or changelog improvements
+   discovered during the process.
+
+Current Manual Steps Versus Future Automation
+---------------------------------------------
+
+Maintainers currently choose the release commit, create the tag, and write
+release notes manually. That keeps release intent explicit.
+
+Future automation could help generate changelog drafts, validate Packagist
+publication, or summarize post-release checks. Those improvements should remain
+separate from this guide unless the release process itself changes.