element-hq / element-hq/synapse

Version picker on documentation site gets stale

Open Beginner friendly
#19,967 0 comments 0 reactions 0 assignees View on GitHub
A-Docs
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.