Version picker on documentation site gets stale
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 65/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- github, javascript
- Domain
- documentation
Research direction
Start with docs/website_files/version-picker.js, especially the fetch call around lines 57-58, and review .github/workflows/docs.yaml to understand when the version data is published. Compare the proposed cache-handling approaches and verify that the picker discovers newly published versions without making unnecessary GitHub API requests.
Written by the indexing model from the issue text.
Description
Problem
When you visit https://element-hq.github.io/synapse/latest/welcome_and_overview.html, the version picker can be stuck with only older Synapse versions available. This is because we configure force-cache to tell the browser to use a cached response if available regardless of if it's stale or not,
force-cache— The browser looks for a matching request in its HTTP cache. If there is a match, fresh or stale, it will be returned from the cache.-- https://developer.mozilla.org/en-US/docs/Web/API/Request/cache
I noticed this because I'm driving the release process and wanted to link some docs for the changelog but I couldn't see the new version on the docs site. Turned out that the new version of the docs was available (CI runs for release-v*, develop, and master) and its only the version picker that is stale.
Potential solutions
We can't really rely on the cache headers from https://api.github.com/repos/element-hq/synapse/git/trees/gh-pages either as it only has cache-control: public, max-age=60, s-maxage=60 (valid for 60 seconds) and the GitHub API only allows 60 API requests per hour when unauthenticated. It's technically just enough to cover us but it's totally unnecessary to spam the GitHub API every minute and we should be respectful that other things on their machine might also want to use the GitHub API.
The fetch API doesn't seem to have a way to force-cache but only up to some expiry time.
We could add ?cache-bust=xxx parameter with a timestamp rounded to the nearest hour/day. This would cause us to only make a new request every hour/day.
Other solutions like storing it with service worker, local storage, etc are pretty heavy-weight and probably not worth the complexity.
- Dominant language
- Python
- Stars
- 4.6k
- Forks
- 608
- Avg merge
- 5d 5h
- Merged PRs (30d)
- 42
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from element-hq/synapse
-
A-Validation T-Defect
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
element-hq/synapse#20188 ·
-
A-URL-Preview
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
element-hq/synapse#20179 · 1 comment ·
-
A-Docs
Difficulty 1/5 1-3 hours Newbie friendliness 78/100
element-hq/synapse#20112 ·
-
A-Packaging
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
element-hq/synapse#20064 ·
-
A-Packaging
Difficulty 1/5 Under an hour Newbie friendliness 84/100
element-hq/synapse#20063 ·
All issues in element-hq/synapse
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100