Skip to content

Commit c0dc95b

Browse files
penelopeysmpenelopeysm
authored
Improvements to docs infrastructure (#497)
* Gitignore Python venv and other temporary files * Fix typo in versions.sh script * Use single Project.toml for entire repo * Include Manifest hashes in GHA cache key Closes #496 * Fix caching in PR preview workflow as well * Generate Manifest.toml before hashing it * Add temp workflow to regenerate docs for #497 * Revert "Add temp workflow to regenerate docs for #497" This reverts commit d34c745. * Expand version check script The action now: - runs on all PRs to main / backport branches - runs on pushes to main / backport branches It always checks that the version of Turing in Project.toml matches that in _quarto.yml. Additionally, if the PR is targeted at main / the push is to the main branch, it also checks that the version of Turing matches the latest release on GitHub. * Don't ignore Manifest, update deps * Check Manifest file in GHA as well * Instantiate project environment in publish workflow * Modify version check action to also suggest updates as a PR * Add comment at the top of version check workflow * Separate version check script into its own file * Don't need --project as the script sets it up
1 parent b65e747 commit c0dc95b

File tree

68 files changed

+1210
-57417
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+1210
-57417
lines changed

‎.github/workflows/preview.yml

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,29 +22,30 @@ jobs:
2222
with:
2323
version: '1.10'
2424

25+
- name: Instantiate Julia environment
26+
run: julia --project=. -e 'using Pkg; Pkg.instantiate()'
27+
2528
- name: Set up Quarto
2629
uses: quarto-dev/quarto-actions/setup@v2
2730

2831
- name: Restore cached _freeze folder
29-
id: cache-primes-restore
32+
id: cache-restore
3033
uses: actions/cache/restore@v4
3134
with:
3235
path: |
3336
_freeze/
34-
key: ${{ runner.os }}-primes-${{ github.run_id }}
35-
restore-keys: |
36-
${{ runner.os }}-primes
37+
key: ${{ runner.os }}-${{ hashFiles('**/Manifest.toml') }}
3738

3839
- name: Render Quarto site
3940
run: quarto render
4041

4142
- name: Save _freeze folder
42-
id: cache-primes-save
43+
id: cache-save
4344
uses: actions/cache/save@v4
4445
with:
4546
path: |
4647
_freeze/
47-
key: ${{ runner.os }}-primes-${{ github.run_id }}
48+
key: ${{ runner.os }}-${{ hashFiles('**/Manifest.toml') }}
4849

4950
- name: Deploy to GitHub Pages
5051
uses: JamesIves/github-pages-deploy-action@v4

‎.github/workflows/publish.yml

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,21 +20,22 @@ jobs:
2020
with:
2121
version: '1.10'
2222

23+
- name: Instantiate Julia environment
24+
run: julia --project=. -e 'using Pkg; Pkg.instantiate()'
25+
2326
- name: Set up Quarto
2427
uses: quarto-dev/quarto-actions/setup@v2
2528

2629
- name: Install jq
2730
run: sudo apt-get install jq
2831

2932
- name: Restore cached _freeze folder
30-
id: cache-primes-restore
33+
id: cache-restore
3134
uses: actions/cache/restore@v4
3235
with:
3336
path: |
3437
_freeze/
35-
key: ${{ runner.os }}-primes-${{ github.run_id }}
36-
restore-keys: |
37-
${{ runner.os }}-primes
38+
key: ${{ runner.os }}-${{ hashFiles('**/Manifest.toml') }}
3839

3940
- name: Extract version from _quarto.yml
4041
id: extract_version
@@ -70,12 +71,12 @@ jobs:
7071
run: mv _site/search.json _site/search_original.json
7172

7273
- name: Save _freeze folder
73-
id: cache-primes-save
74+
id: cache-save
7475
uses: actions/cache/save@v4
7576
with:
7677
path: |
7778
_freeze/
78-
key: ${{ runner.os }}-primes-${{ github.run_id }}
79+
key: ${{ runner.os }}-${{ hashFiles('**/Manifest.toml') }}
7980

8081
- name: Fetch search_original.json from main site
8182
run: curl -O https://raw.githubusercontent.com/TuringLang/turinglang.github.io/gh-pages/search_original.json

‎.github/workflows/vcheck.yml

Lines changed: 0 additions & 43 deletions
This file was deleted.

‎.github/workflows/version_check.jl

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# Set up a temporary environment just to run this script
2+
using Pkg
3+
Pkg.activate(temp=true)
4+
Pkg.add(["YAML", "TOML", "JSON", "HTTP"])
5+
import YAML
6+
import TOML
7+
import JSON
8+
import HTTP
9+
10+
PROJECT_TOML_PATH = "Project.toml"
11+
QUARTO_YML_PATH = "_quarto.yml"
12+
MANIFEST_TOML_PATH = "Manifest.toml"
13+
14+
function major_minor_match(vs...)
15+
first = vs[1]
16+
all(v.:major == first.:major && v.:minor == first.:minor for v in vs)
17+
end
18+
19+
function major_minor_patch_match(vs...)
20+
first = vs[1]
21+
all(v.:major == first.:major && v.:minor == first.:minor && v.:patch == first.:patch for v in vs)
22+
end
23+
24+
"""
25+
Update the version number in Project.toml to match `target_version`.
26+
27+
This uses a naive regex replacement on lines, i.e. sed-like behaviour. Parsing
28+
the file, editing the TOML and then re-serialising also works and would be more
29+
correct, but the entries in the output file can end up being scrambled, which
30+
would lead to unnecessarily large diffs in the PR.
31+
"""
32+
function update_project_toml(filename, target_version::VersionNumber)
33+
lines = readlines(filename)
34+
open(filename, "w") do io
35+
for line in lines
36+
if occursin(r"^Turing\s*=\s*\"\d+\.\d+\"\s*$", line)
37+
println(io, "Turing = \"$(target_version.:major).$(target_version.:minor)\"")
38+
else
39+
println(io, line)
40+
end
41+
end
42+
end
43+
end
44+
45+
"""
46+
Update the version number in _quarto.yml to match `target_version`.
47+
48+
See `update_project_toml` for implementation rationale.
49+
"""
50+
function update_quarto_yml(filename, target_version::VersionNumber)
51+
# Don't deserialise/serialise as this will scramble lines
52+
lines = readlines(filename)
53+
open(filename, "w") do io
54+
for line in lines
55+
m = match(r"^(\s+)- text:\s*\"v\d+\.\d+\"\s*$", line)
56+
if m !== nothing
57+
println(io, "$(m[1])- text: \"v$(target_version.:major).$(target_version.:minor)\"")
58+
else
59+
println(io, line)
60+
end
61+
end
62+
end
63+
end
64+
65+
# Retain the original version number string for error messages, as
66+
# VersionNumber() will tack on a patch version of 0
67+
quarto_yaml = YAML.load_file(QUARTO_YML_PATH)
68+
quarto_version_str = quarto_yaml["website"]["navbar"]["right"][1]["text"]
69+
quarto_version = VersionNumber(quarto_version_str)
70+
println("_quarto.yml version: ", quarto_version_str)
71+
72+
project_toml = TOML.parsefile(PROJECT_TOML_PATH)
73+
project_version_str = project_toml["compat"]["Turing"]
74+
project_version = VersionNumber(project_version_str)
75+
println("Project.toml version: ", project_version_str)
76+
77+
manifest_toml = TOML.parsefile(MANIFEST_TOML_PATH)
78+
manifest_version = VersionNumber(manifest_toml["deps"]["Turing"][1]["version"])
79+
println("Manifest.toml version: ", manifest_version)
80+
81+
errors = []
82+
83+
if ENV["TARGET_IS_MASTER"] == "true"
84+
# This environment variable is set by the GitHub Actions workflow. If it is
85+
# true, fetch the latest version from GitHub and update files to match this
86+
# version if necessary.
87+
88+
resp = HTTP.get("https://api.github.com/repos/TuringLang/Turing.jl/releases/latest")
89+
latest_version = VersionNumber(JSON.parse(String(resp.body))["tag_name"])
90+
println("Latest Turing.jl version: ", latest_version)
91+
92+
if !major_minor_match(latest_version, project_version)
93+
push!(errors, "$(PROJECT_TOML_PATH) out of date")
94+
println("$(PROJECT_TOML_PATH) is out of date; updating")
95+
update_project_toml(PROJECT_TOML_PATH, latest_version)
96+
end
97+
98+
if !major_minor_match(latest_version, quarto_version)
99+
push!(errors, "$(QUARTO_YML_PATH) out of date")
100+
println("$(QUARTO_YML_PATH) is out of date; updating")
101+
update_quarto_yml(QUARTO_YML_PATH, latest_version)
102+
end
103+
104+
if !major_minor_patch_match(latest_version, manifest_version)
105+
push!(errors, "$(MANIFEST_TOML_PATH) out of date")
106+
# Attempt to automatically update Manifest
107+
println("$(MANIFEST_TOML_PATH) is out of date; updating")
108+
old_env = Pkg.project().path
109+
Pkg.activate(".")
110+
Pkg.update()
111+
# Check if versions match now, error if not
112+
Pkg.activate(old_env)
113+
manifest_toml = TOML.parsefile(MANIFEST_TOML_PATH)
114+
manifest_version = VersionNumber(manifest_toml["deps"]["Turing"][1]["version"])
115+
if !major_minor_patch_match(latest_version, manifest_version)
116+
push!(errors, "Failed to update $(MANIFEST_TOML_PATH) to match latest Turing.jl version")
117+
end
118+
end
119+
120+
if isempty(errors)
121+
println("All good")
122+
else
123+
error("The following errors occurred during version checking: \n", join(errors, "\n"))
124+
end
125+
126+
else
127+
# If this is not true, then we are running on a backport-v* branch, i.e. docs
128+
# for a non-latest version. In this case we don't attempt to fetch the latest
129+
# patch version from GitHub to check the Manifest (we could, but it is more
130+
# work as it would involve paging through the list of releases). Instead,
131+
# we just check that the minor versions match.
132+
if !major_minor_match(quarto_version, project_version, manifest_version)
133+
error("The minor versions of Turing.jl in _quarto.yml, Project.toml, and Manifest.toml are inconsistent:
134+
- _quarto.yml: $quarto_version_str
135+
- Project.toml: $project_version_str
136+
- Manifest.toml: $manifest_version
137+
")
138+
end
139+
end

‎.github/workflows/version_check.yml

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# This action checks that the minor versions of Turing.jl specified in the
2+
# Project.toml, _quarto.yml, and Manifest.toml files are consistent.
3+
#
4+
# For pushes to master or PRs to master, it additionally also checks that the
5+
# version specified in Manifest.toml matches the latest release on GitHub.
6+
#
7+
# If any discrepancies are observed, it will open a PR to fix them.
8+
9+
name: Check Turing.jl version consistency
10+
on:
11+
push:
12+
branches:
13+
- master
14+
- backport-*
15+
pull_request:
16+
branches:
17+
- master
18+
- backport-*
19+
workflow_dispatch:
20+
21+
jobs:
22+
check-version:
23+
runs-on: ubuntu-latest
24+
25+
permissions:
26+
contents: write
27+
pull-requests: write
28+
29+
env:
30+
# Determine whether the target branch is master (i.e. this is a push to
31+
# master or a PR to master).
32+
TARGET_IS_MASTER: ${{ (github.event_name == 'push' && github.ref_name == 'master') || (github.event_name == 'pull_request' && github.base_ref == 'master') }}
33+
# Disable precompilation as it takes a long time and is not needed for this workflow
34+
JULIA_PKG_PRECOMPILE_AUTO: 0
35+
36+
steps:
37+
- name: Checkout
38+
uses: actions/checkout@v4
39+
40+
- name: Setup Julia
41+
uses: julia-actions/setup-julia@v2
42+
43+
- name: Log GitHub context variables
44+
run: |
45+
echo github.event_name: ${{ github.event_name }}
46+
echo github.ref_name: ${{ github.ref_name }}
47+
echo github.base_ref: ${{ github.base_ref }}
48+
echo TARGET_IS_MASTER: ${{ env.TARGET_IS_MASTER }}
49+
50+
- name: Check version consistency
51+
continue-on-error: true
52+
run: julia --color=yes .github/workflows/version_check.jl
53+
54+
- name: Create a PR with suggested changes
55+
id: create_pr
56+
if: env.TARGET_IS_MASTER
57+
uses: peter-evans/create-pull-request@v6
58+
with:
59+
base: ${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
60+
branch: update-turing-version/${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}
61+
commit-message: "Update Turing.jl version to match latest release"
62+
body: "This PR is automatically generated by the `version_check.yml` GitHub Action."
63+
title: "Update Turing.jl version to match latest release"
64+
65+
- name: Comment on PR about suggested changes
66+
if: ${{ github.event_name == 'pull_request' && steps.create_pr.outputs.pull-request-operation == 'created' }}
67+
uses: thollander/actions-comment-pull-request@v2
68+
with:
69+
message: |
70+
Hello! The versions of Turing.jl in your `Project.toml`, `_quarto.yml`, and/or `Manifest.toml` did not match the latest release version found on GitHub (https://github.com/TuringLang/Turing.jl/releases/latest).
71+
72+
I've made a PR to update these files to match the latest release: ${{ steps.create_pr.outputs.pull-request-url }}
73+
74+
Please review the changes and merge the PR if they look good.

‎.gitignore

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,12 +13,13 @@
1313
/tutorials/**/index_files/*
1414
Testing/
1515
/*/*/jl_*/
16-
/Manifest.toml
17-
/test/Manifest.toml
1816
.vscode
1917
_freeze
2018
_site
2119
.quarto
2220
/.quarto/
2321
changelog.qmd
24-
versions.qmd
22+
versions.qmd
23+
tmp.gif
24+
.venv
25+
venv

0 commit comments

Comments
 (0)