From 54080ad97fd9d818f97e9f73c4d3758eb585a5fe Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 27 May 2021 18:32:21 +0100 Subject: [PATCH 1/5] Additionally deploy to a folder named after current Synapse version Doing so will allow us to build up releases of the docs as we create and push to release branches. In the future we'll have some UI on the website to switch between versions, but for now you can simple just change 'develop' to 'v1.2' in the URL. --- .github/workflows/docs.yaml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index a746ae6de3a8..0d03b7568e9d 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -3,7 +3,10 @@ name: Deploy the documentation on: push: branches: + # For bleeding-edge documentation - develop + # For documentation specific to a release + - 'release-v*' workflow_dispatch: @@ -22,6 +25,7 @@ jobs: - name: Build the documentation run: mdbook build + # Deploy to the latest documentation directories - name: Deploy latest documentation uses: peaceiris/actions-gh-pages@068dc23d9710f1ba62e86896f84735d869951305 # v3.8.0 with: @@ -29,3 +33,26 @@ jobs: keep_files: true publish_dir: ./book destination_dir: ./develop + + - name: Get the current Synapse version + id: vars + # The $GITHUB_REF value for a branch looks like `refs/heads/release-v1.2`. We do some + # bash magic to remove the "refs/heads/release-v" bit from this, to end up with + # "1.2" - our major/minor version number. + run: echo ::set-output name=synapse-version::${GITHUB_REF#refs/heads/release-v} + + # Deploy to the version-specific directory + - name: Deploy release-specific documentation + # We only carry out this step if we're running on a release branch, + # and the current Synapse version does not have "rc" in the name. + # + # The result is that only full releases are deployed, but can be + # updated if the release branch gets retroactive fixes. + if: ${{ startsWith( github.ref, 'refs/heads/release-v' ) && !contains( steps.vars.outputs.synapse-version, 'rc') }} + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + keep_files: true + publish_dir: ./book + # The resulting documentation will end up in a directory named `vX.Y`. + destination_dir: ./v${{ steps.vars.outputs.synapse-version }} From 699daa6e179227c82bc2842bd92447d3b1223cea Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Thu, 17 Jun 2021 16:49:17 +0100 Subject: [PATCH 2/5] Changelog --- changelog.d/10198.doc | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 changelog.d/10198.doc diff --git a/changelog.d/10198.doc b/changelog.d/10198.doc new file mode 100644 index 000000000000..e69de29bb2d1 From b5ee31b2b96d88e2c0a3121dd98b137f2bbf7754 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 18 Jun 2021 16:03:16 +0100 Subject: [PATCH 3/5] Properly prevent rc versions from causing a deploy We were checking a version number derived from the branch for whether it included "rc" - which didn't make sense, branches never have "rc" in the name. Instead, we use Synapse's __version__ string to perform the rc check. There's some potential to using tags instead here, but this works for now... --- .github/workflows/docs.yaml | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 0d03b7568e9d..5d258ffad2e3 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,9 +37,15 @@ jobs: - name: Get the current Synapse version id: vars # The $GITHUB_REF value for a branch looks like `refs/heads/release-v1.2`. We do some - # bash magic to remove the "refs/heads/release-v" bit from this, to end up with - # "1.2" - our major/minor version number. - run: echo ::set-output name=synapse-version::${GITHUB_REF#refs/heads/release-v} + # bash magic to remove the "refs/heads/release-v" bit from this, to end up with "1.2", + # our major/minor version number, and set this to a var called `branch-version`. + # + # We then use some python to get Synapse's full version string, which may look + # like "1.2.3rc4". We set this to a var called `synapse-version`. We use this + # to determine if this release is still an RC, and if so block deployment. + run: | + echo ::set-output name=branch-version::${GITHUB_REF#refs/heads/release-v} + echo ::set-output name=synapse-version::`python3 -c 'import synapse; print(synapse.__version__)'` # Deploy to the version-specific directory - name: Deploy release-specific documentation @@ -55,4 +61,4 @@ jobs: keep_files: true publish_dir: ./book # The resulting documentation will end up in a directory named `vX.Y`. - destination_dir: ./v${{ steps.vars.outputs.synapse-version }} + destination_dir: ./v${{ steps.vars.outputs.branch-version }} From 379f00857fb15872da942802c15dd9397cf62844 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 18 Jun 2021 18:10:51 +0100 Subject: [PATCH 4/5] Actually put some text in the changelog --- changelog.d/10198.doc | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog.d/10198.doc b/changelog.d/10198.doc index e69de29bb2d1..8d1aeab1a7e7 100644 --- a/changelog.d/10198.doc +++ b/changelog.d/10198.doc @@ -0,0 +1 @@ +Deploy a snapshot of the documentation website upon each new Synapse release. From b4682dd0c61e82ee22ece9bb02aaa6754eacb74c Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 18 Jun 2021 18:22:01 +0100 Subject: [PATCH 5/5] turns out it's not bash-specific --- .github/workflows/docs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 5d258ffad2e3..23b8d7f9093e 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -37,7 +37,7 @@ jobs: - name: Get the current Synapse version id: vars # The $GITHUB_REF value for a branch looks like `refs/heads/release-v1.2`. We do some - # bash magic to remove the "refs/heads/release-v" bit from this, to end up with "1.2", + # shell magic to remove the "refs/heads/release-v" bit from this, to end up with "1.2", # our major/minor version number, and set this to a var called `branch-version`. # # We then use some python to get Synapse's full version string, which may look