Skip to content

Commit 5ad5592

Browse files
larrysingleton007franciscojavierarceo
larrysingleton007
and
franciscojavierarceo
authored
fix: Automate versioned documentation publication (#6763)
* fix: Automate versioned documentation publication Fixes #6762 Signed-off-by: Larry Singleton <[email protected]> * fix: Add standalone documentation publishing Signed-off-by: Larry Singleton <[email protected]> --------- Signed-off-by: Larry Singleton <[email protected]> Co-authored-by: Francisco Javier Arceo <[email protected]>
1 parent 2573693 commit 5ad5592

4 files changed

Lines changed: 675 additions & 5 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,11 @@ on:
1818
required: true
1919
default: true
2020
type: boolean
21+
publish_docs_version:
22+
description: 'Publish docs for an existing release (for example, 0.66.0)'
23+
required: false
24+
default: ""
25+
type: string
2126
workflow_call:
2227
inputs:
2328
dry_run:
@@ -35,10 +40,19 @@ on:
3540
required: true
3641
default: true
3742
type: boolean
43+
publish_docs_version:
44+
description: 'Publish docs for an existing release (for example, 0.66.0)'
45+
required: false
46+
default: ""
47+
type: string
48+
secrets:
49+
GITBOOK_TOKEN:
50+
description: 'Token used to publish versioned documentation'
51+
required: true
3852

3953
jobs:
4054
get_dry_release_versions:
41-
if: github.repository == 'feast-dev/feast'
55+
if: github.repository == 'feast-dev/feast' && inputs.publish_docs_version == ''
4256
runs-on: ubuntu-latest
4357
env:
4458
GITHUB_TOKEN: ${{ github.event.inputs.token }}
@@ -196,3 +210,53 @@ jobs:
196210
run: |
197211
git checkout -B stable origin/${GITHUB_REF#refs/heads/}
198212
git push origin stable --force
213+
214+
publish_versioned_docs:
215+
name: Publish versioned documentation
216+
if: github.event.inputs.dry_run == 'false'
217+
runs-on: ubuntu-latest
218+
needs: [get_dry_release_versions, release]
219+
permissions:
220+
contents: write
221+
env:
222+
GITHUB_TOKEN: ${{ github.event.inputs.token }}
223+
GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
224+
GITBOOK_ORG_ID: ${{ vars.GITBOOK_ORG_ID }}
225+
GITBOOK_SITE_ID: ${{ vars.GITBOOK_SITE_ID }}
226+
steps:
227+
- name: Checkout code
228+
uses: actions/checkout@v4
229+
with:
230+
fetch-depth: 0
231+
persist-credentials: false
232+
233+
- name: Publish released documentation
234+
run: |
235+
python infra/scripts/release/publish_versioned_docs.py \
236+
--version "${{ needs.get_dry_release_versions.outputs.next_version }}"
237+
238+
publish_existing_version_docs:
239+
name: Publish documentation for an existing release
240+
if: github.repository == 'feast-dev/feast' && inputs.publish_docs_version != ''
241+
runs-on: ubuntu-latest
242+
permissions:
243+
contents: write
244+
env:
245+
GITHUB_TOKEN: ${{ inputs.token }}
246+
GITBOOK_TOKEN: ${{ secrets.GITBOOK_TOKEN }}
247+
GITBOOK_ORG_ID: ${{ vars.GITBOOK_ORG_ID }}
248+
GITBOOK_SITE_ID: ${{ vars.GITBOOK_SITE_ID }}
249+
steps:
250+
- name: Checkout code
251+
uses: actions/checkout@v4
252+
with:
253+
fetch-depth: 0
254+
persist-credentials: false
255+
256+
- name: Publish released documentation
257+
run: |
258+
args=(--version "${{ inputs.publish_docs_version }}")
259+
if [[ "${{ inputs.dry_run }}" == "true" ]]; then
260+
args+=(--dry-run)
261+
fi
262+
python infra/scripts/release/publish_versioned_docs.py "${args[@]}"

‎docs/project/release-process.md‎

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -110,17 +110,35 @@ We verify the building the wheels and Docker images in **your fork** of Feast, n
110110
- [Maven repo (feast-datatypes, feast-serving-client)](https://mvnrepository.com/artifact/dev.feast)
111111

112112
### 4. (for minor releases) Post-release steps
113-
#### 4a: Creating a new branch
114-
Create a new branch based on master (i.e. v0.22-branch) and push to the main Feast repo. This will be where
115-
cherry-picks go for future patch releases and where documentation will point.
113+
#### 4a: Versioned branch and documentation publication
114+
115+
The `publish_versioned_docs` release job creates the `v<major>.<minor>-branch` maintenance branch
116+
at the released tag, imports that branch into a versioned GitBook space, and makes the new space
117+
the public default. It verifies the final GitBook state before succeeding.
118+
119+
The repository must define `GITBOOK_ORG_ID` and `GITBOOK_SITE_ID` variables and a scoped
120+
`GITBOOK_TOKEN` secret with permission to create and update spaces, update the site, and publish
121+
it. The release token must be able to create the maintenance branch.
122+
123+
The job is safe to rerun. It reuses matching branches and spaces, but it will not move an existing
124+
maintenance branch that points somewhere other than the released tag. It also leaves the previous
125+
documentation version as the public default until the new branch has imported successfully.
126+
127+
To publish documentation independently of a release, run the `release` workflow from `master` and
128+
set `publish_docs_version` to an existing release such as `0.66.0`. When this input is set, the
129+
release jobs are skipped and only the versioned documentation job runs. Keep `dry_run` enabled for
130+
the first run, then disable it to create or verify the maintenance branch and publish its GitBook
131+
space. The standalone job does not move `stable` or create a release.
116132

117133
#### 4b: Adding a high level summary in the GitHub release notes
118134
By default, Semantic Release will pull in messages from commits (features vs fixes, etc). But this is hard to digest,
119135
so it helps to have a high level overview. See https://github.com/feast-dev/feast/releases for the releases.
120136

121137
#### 4c: Update documentation
122138

123-
In the Feast Gitbook:
139+
If the automated documentation job fails, use its error as the recovery point and complete the
140+
remaining steps in the Feast GitBook:
141+
124142
1. Create a new space within the Feast collection
125143
2. Go to the overflow menu on the top -> Synchronize with Git
126144
1. Specify GitHub as the provider

0 commit comments

Comments
 (0)