Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edit on GitHub link is broken on our stable docs #1237

Closed
drammock opened this issue Mar 8, 2023 · 1 comment · Fixed by #1246
Closed

Edit on GitHub link is broken on our stable docs #1237

drammock opened this issue Mar 8, 2023 · 1 comment · Fixed by #1246

Comments

@drammock
Copy link
Collaborator

drammock commented Mar 8, 2023

On our dev docs it works: the link on this page goes here

On our the same page in our stable docs the link goes here which is a GitHub 404 page.

The difference in the links is that the dev docs link goes to github.com/.../edit/main/.../index.md while the stable docs goes to github.com/.../edit/<commit hash>/.../index.md.

I'm pretty sure the issue is that GitHub won't let someone propose changes to something other than the tip of a branch: if I go to a file on one of our very old branches I get an active "edit" button on GitHub. But since we don't habitually keep separate branches for our releases, the point in history associated with stable is not the tip of a branch, it's just a tag on main, so you get this:

no-edit

Two solutions I can think of are:

  1. always have the edit link go to main. If we delete or rename a file between stable and main it will still 404, but for most pages on stable the link will work
  2. make a branch called stable and add it to our release process to do a squash-merge from main to stable once the release is cut. Then the edit links can all be github.com/.../edit/stable/... and should work.

I prefer option 1; if folks are proposing changes to our docs, most of the time we'll want those changes on main / in the dev version too, not just on stable, and if they're important changes we can cut a new patch release to update the stable docs right away too. Also I think we're not likely to delete or rename pages very often so the downside to option 1 seems minor.

Originally posted by @drammock in #1200 (comment)

@12rambau
Copy link
Collaborator

12rambau commented Mar 8, 2023

I'm +1 for option 1 as well

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants