diff --git a/.github/wiki b/.github/wiki index b56e5a583f..f2283d4428 160000 --- a/.github/wiki +++ b/.github/wiki @@ -1 +1 @@ -Subproject commit b56e5a583f633d54c6615d811231b307a2ceae56 +Subproject commit f2283d4428fa80dc1cbfaaf62e4fd549e8522f54 diff --git a/docs/internals/index.rst b/docs/internals/index.rst index 17056308b0..1286bad84b 100644 --- a/docs/internals/index.rst +++ b/docs/internals/index.rst @@ -9,3 +9,4 @@ step. :maxdepth: 1 architecture + release-publishing diff --git a/docs/internals/release-publishing.rst b/docs/internals/release-publishing.rst new file mode 100644 index 0000000000..197775f635 --- /dev/null +++ b/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 + git push origin + +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 `_. +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.