element-hq / element-hq/synapse
Version picker on documentation site gets stale
- Dominant language
- Python
- Stars
- 4.6k
- Forks
- 600
- Avg merge
- 5d 22h
- Merged PRs (30d)
- 51
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,
https://github.com/element-hq/synapse/blob/0512511f87c4436bba63b54e95ee330104cb91cb/docs/website_files/version-picker.js#L57-L58
> `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`](https://github.com/element-hq/synapse/blob/0512511f87c4436bba63b54e95ee330104cb91cb/.github/workflows/docs.yaml#L5-L11)) 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.
Contributor guide
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.
Assessment
- Tech stack
- github, javascript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100