Merge pull request #39 from wbcsd/automate-release

Automate releases

.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version"
+        required: true
+      draft:
+        description: "Flags if the release is a Consultation Draft"
+        default: "false"
+        required: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set status
+        id: set-status
+        run: |
+          if [ "${{ github.event.inputs.draft }}" != "false" ]; then
+            echo "::set-output name=status::true"
+          else
+            echo "::set-output name=status::false"
+          fi
+
+      - name: Create release
+        if: ${{ inputs.draft != '' }}
+        run: DRAFT=${{steps.set-status.outputs.status}} sh ./spec/release.sh
+
+      - name: Get date
+        id: date
+        run: echo "::set-output name=year::$(date +'%Y')" && echo "::set-output name=date::$(date +'%Y%m%d')"
+      - name: Push release to tr/${{steps.date.outputs.year}}
+        uses: cpina/github-action-push-to-another-repository@main
+        env:
+          SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
+        with:
+          source-directory: "spec/release"
+          destination-github-username: "wbcsd"
+          destination-repository-name: "tr"
+          user-email:
+          target-directory: ./${{steps.date.outputs.year}}/data-exchange-protocol-${{steps.date.outputs.date}}
+          target-branch: release-v${{inputs.version}}-${{steps.date.outputs.date}}
+          create-target-branch-if-needed: true
+          commit-message: "Release v${{inputs.version}}"
+      - name: Push release to wbcsd/tr
+        uses: cpina/github-action-push-to-another-repository@main
+        env:
+          SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
+        with:
+          source-directory: "spec/release"
+          destination-github-username: "wbcsd"
+          destination-repository-name: "tr"
+          user-email:
+          target-directory: ./data-exchange-protocol
+          target-branch: release-v${{inputs.version}}-${{steps.date.outputs.date}}
+          create-target-branch-if-needed: true
+          commit-message: "Release v${{inputs.version}}"
+      # - name: Create Pull Request
+      #   env:
+      #     SSH_DEPLOY_KEY: ${{ secrets.SSH_DEPLOY_KEY }}
+      #   run: |
+      #     gh api \
+      #     --method POST \
+      #     -H "Accept: application/vnd.github+json" \
+      #     -H "X-GitHub-Api-Version: 2022-11-28" \
+      #     /repos/wbcsd/tr/actions/workflows/release.yml/dispatches \
+      #     -f "ref=open-pr" -f "inputs[version]=${{inputs.version}}"

spec/RELEASE.md

@@ -0,0 +1,52 @@
+# Release Instructions
+
+Follow the instructions below to trigger a release of the Technical Specifications.
+
+> To trigger a release, you need to have sufficient permissions on the `wbcsd` GitHub organiztion, as well as on this (`wbcsd/data-exchange-protocol`) repositiory and in the target repository [`wbcsd/tr`](https://github.com/wbcsd/tr).
+
+> You also need to have the GitHub CLI tool locally installed and be logged in to GitHub from your local terminal. See https://cli.github.com/ for further information.
+
+## 1. Preparation
+
+Make sure your `specs/v2/index.bs` file is ready. In particular, you should double check if:
+- The version number (`Text Macro: VERSION <x.y.z>`) contains a date (e.g. `2.2.1-20240521`). This should only be used for the work in progress version of the Technical Specifications and should not be included in any release.
+- There is a changelog entry, indicating that a release is being made, and whether it is a consultation draft or a stable version.
+
+## 2. Trigger the Release Workflow
+
+On your command line, navigate to the `data-exchange-protocol` directory.
+
+Use the following command to trigger the release workflow from there:
+```
+gh workflow run release -f version=<x.y.z>
+```
+Make sure to replace `<x.y.z>` by the version of the Technical Specifications being released (e.g., `2.2.1`).
+
+With the command above, the resulting Technical Specifications will be tagged as **Stable Release**.
+
+If instead you wish to trigger a consultation draft, pass the `draft=true` input as follows:
+```
+gh workflow run release -f version=<x.y.z> -f draft=true
+```
+The resulting document will be tagged as **Consultation Draft**.
+
+## 3. Open a PR in the [`wbcsd/tr`](https://github.com/wbcsd/tr) Repository
+
+On your browser, navigate to the [`wbcsd/tr`](https://github.com/wbcsd/tr) repository.
+
+At the top of the page, you shall see a yellow box and a green button to open a Pull Request, like the following:
+
+<img width="920" alt="Screenshot 2024-05-21 at 19 20 01" src="https://github.com/wbcsd/data-exchange-protocol/assets/100690574/8cb3a8fb-8a9a-41ee-8c4a-52d0d0798987">
+
+> Note that the branch name will include the date. This is intended and it does not mean that your version number is wrong. Note also that this screenshot is just an example.
+
+Click the green button "Compare & pull request". On the new page, scroll down and click the green button "Create pull request."
+
+<img width="935" alt="Screenshot 2024-05-21 at 19 20 30" src="https://github.com/wbcsd/data-exchange-protocol/assets/100690574/86fdbfba-2d88-4e3d-9036-6c2460e347d8">
+
+## 4. Merge the PR
+
+Once you are ready (e.g., someone else from the team has reviewed it), merge the PR by clicking the green "Merge pull request" button.
+
+<img width="909" alt="Screenshot 2024-05-21 at 19 21 41" src="https://github.com/wbcsd/data-exchange-protocol/assets/100690574/befca359-1b1c-4c06-9435-e5cd07c50852">
+

spec/release.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+
+cd spec/v2
+pip3 install bikeshed && bikeshed update
+mv header.include header.include_temp
+mv header.include_release header.include
+rm index.html
+
+
+
+if [ "$DRAFT" = "true" ]; then
+    RELEASE_STATUS="RELEASE Consultation Draft"
+else
+    RELEASE_STATUS="RELEASE Stable Release"
+fi
+make STATUS="$RELEASE_STATUS"
+
+mkdir -p ../release/diagrams
+
+for i in diagrams/*.svg; do
+    cp $i ../release/diagrams/
+done
+
+cp index.html ../release/
+
+mv header.include header.include_release
+mv header.include_temp header.include

spec/v2/Makefile

@@ -1,6 +1,7 @@
 DIAGRAMS := $(patsubst %.mmd,%.svg,$(wildcard diagrams/*.mmd))
 OUTDIR := ../../upload/v2
 MMDC := mmdc
+STATUS ?= ""
 
 all: index.html
 
@@ -14,7 +15,7 @@ publish: index.html computed-metadata.include
 	cp $^ $(OUTDIR)
 
 index.html: index.bs $(DIAGRAMS)
-	bikeshed spec $< $@
+	bikeshed spec $< $@ --md-text-macro="$(STATUS)"
 
 %.svg: %.mmd $(MMDC)
 	$(MMDC) -i $< -o $@