{% for page in pages %}
+ {% if page.slug != 'pie-maintainers-handbook' %}
{{ page.content|preg_replace('~\./docs/~', '')|raw }}
+ {% endif %}
{% endfor %}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index c376b2be..73ddf2e2 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,9 +1,9 @@
-name: "Publish the PHAR for Releases"
+name: "Publish a draft release with PHAR attached"
on:
- release:
- types:
- - published
+ push:
+ tags:
+ - '*'
permissions:
contents: read
@@ -17,10 +17,32 @@ jobs:
attestations: write
uses: ./.github/workflows/build-phar.yml
- release-phar:
+ create-draft-release:
runs-on: ubuntu-latest
needs:
- build-phar
+ permissions:
+ # contents:write is required to create the draft release
+ contents: write
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-tags: 'true'
+ ref: ${{ github.ref }}
+ # The changelog is generated locally using jwage/changelog-generator and
+ # that forms the signed tag body. The `--notes-from-tag` option below
+ # will copy the release notes from the tag so it will contain the changelog
+ # Note we must create a *draft* release first, to allow attaching assets
+ # before the release is finalised when using immutable releases.
+ - name: Create draft release from tag
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: gh release create "${{ github.ref_name }}" --title "${{ github.ref_name }}" --draft --notes-from-tag
+
+ release-phar:
+ runs-on: ubuntu-latest
+ needs:
+ - create-draft-release
permissions:
# contents:write is required to upload the binaries to the release.
contents: write
@@ -33,11 +55,15 @@ jobs:
env:
GH_TOKEN: ${{ github.token }}
run: gh attestation verify pie.phar --repo ${{ github.repository }}
- - name: Upload binaries to release
- uses: softprops/action-gh-release@v2
- if: ${{startsWith(github.ref, 'refs/tags/') }}
- with:
- files: pie.phar
+ # Once the PHAR has been attached to the release, it is ready for review
+ # before publishing it. Note that if immutable releases are enabled,
+ # the tag, pre-release/latest release flag, and all assets become
+ # immutable, so checking this over is a manual exercise.
+ # More info: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases
+ - name: Attach an asset to the draft release
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: gh release upload "${{ github.ref_name }}" "pie.phar" --clobber
build-and-push-docker-image:
if: ${{ startsWith(github.ref, 'refs/tags/') }}
diff --git a/.gitignore b/.gitignore
index 68693cc2..49bf644b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,3 +9,4 @@ box.json
box.phar
pie.phar
/docs-package/
+CHANGELOG-*.md
diff --git a/docs/pie-maintainers-handbook.md b/docs/pie-maintainers-handbook.md
new file mode 100644
index 00000000..a275e4bf
--- /dev/null
+++ b/docs/pie-maintainers-handbook.md
@@ -0,0 +1,64 @@
+---
+title: PIE Maintainers Handbook
+order: 3
+---
+# PIE Maintainers Handbook
+
+## Branching strategy
+
+At the moment, we operate a single `main` branch, and feature branches. In the
+future, to better facilitate patch versions, we may switch to a versioned
+branching strategy.
+
+## Release process
+
+Make sure you have the latest version to be released, for example, one of:
+
+```shell
+# Using git reset (note: discards any local commits on `main`)
+git checkout main && git fetch upstream && git reset --hard upstream/main
+# or, using git pull (use `--ff-only` to avoid making merge commits)
+git checkout main && git pull --ff-only upstream main
+```
+
+Prepare a changelog, set the version and milestone to be released, e.g.:
+
+```shell
+PIE_VERSION=1.3.0
+PIE_MILESTONE=$PIE_VERSION
+```
+
+> [!TIP]
+> For pre-releases, you can set the version/milestone to be different, e.g.:
+>
+> ```shell
+> PIE_VERSION=1.3.0-alpha.2
+> PIE_MILESTONE=1.3.0
+> ```
+>
+> This will tag/release with the `1.3.0-alpha.2` version, but will generate the
+> changelog based on the `1.3.0` milestone in GitHub.
+
+Then generate the changelog file:
+
+```shell
+composer require --dev -W jwage/changelog-generator --no-interaction
+vendor/bin/changelog-generator generate --user=php --repository=pie --milestone=$PIE_MILESTONE > CHANGELOG-$PIE_VERSION.md
+git checkout -- composer.*
+composer install
+```
+
+Check you are happy with the contents of the changelog. Create a signed tag:
+
+```shell
+git tag -s $PIE_VERSION -F CHANGELOG-$PIE_VERSION.md
+git push upstream $PIE_VERSION
+```
+
+The release pipeline will run, which will create a **draft** release, build the
+PHAR file, and attach it. You must then go to the draft release on GitHub,
+verify everything is correct, and publish the release.
+
+```shell
+rm CHANGELOG-$PIE_VERSION.md
+```