Repository navigation
Contribution guidelines do not cover how to PR fixes for docs #221
Description
The documentation does require to start PRs from development. However, the readthedocs.io always points to master and fixes for stable docs should therefore be made by pointing to master and starting from master.
Otherwise we might face the uncomfortable situation of
- either merging unstable code from
developmentintomaster - or have to wait for the fix to be released until
developmentis stable and mergeable
The contribution guidelines should therefore have their own section on how to contribute to the docs.
See #220 (comment)
Activity
jorenvandeweyer commentedon Aug 26, 2023
Can we set the default branch to merge to development instead of master?
jankapunkt commentedon Aug 26, 2023
@jorenvandeweyer done
dhensby commentedon Jun 16, 2026
The specific ask here — a docs-contribution section — is now in place (
CONTRIBUTING.md→## Documentation: the Vitepress workflow, editing theguidesection, the auto-generatedapidocs, and building).But triaging this surfaced a bigger, related problem worth fixing: our contribution guidance still describes a gitflow model and points contributors at a
developmentbranch (git checkout development, "target thedevelopmentbranch and notmaster"). That workflow is a bit out of date compared to more modern development flows — and it's the very workflow that let a fix land ondevelopmentand never reach a release (e.g. the refresh-token scope-validation fix that sat ondevelopment, missed 5.3.0, and had to be recovered in #441).I'd propose we switch to GitHub Flow and retire the
developmentbranch:masteris always deployable, protected, and gated by CI on every PR (which we already have). Benefits:developmentthat never make it into a release.master, with prereleases onnext/N.xvia npm dist-tags.Keeping this open to track updating
CONTRIBUTING.mdto GitHub Flow and removing the staledevelopment-branch guidance. cc @jankapunkt