Proposal: move docs into repo permanently once a version drops support #54

Open
opened 2023-07-28 00:28:41 +00:00 by jolheiser · 6 comments
Owner

I propose that once a version has been released (or after we drop official support?), we move the docs from that branch to this repo directly.

It means less cloning, and theoretically nothing much should change from that point on for that version of the docs.
Plus, if we ever have to do a larger refactor, it will be easier than a state where version X had X layout, version Y has Y layout, etc. as we continue to evolve the docs.

Note that I'm referring to the main repo, auxiliary repo docs probably don't need the same treatment.

Originally posted by @jolheiser in /gitea/gitea-docusaurus/issues/1#issuecomment-745440

I propose that once a version has been released (or after we drop official support?), we move the docs from that branch to this repo directly. It means less cloning, and theoretically nothing much should change from that point on for that version of the docs. Plus, if we ever have to do a larger refactor, it will be easier than a state where version X had X layout, version Y has Y layout, etc. as we continue to evolve the docs. Note that I'm referring to the main repo, auxiliary repo docs probably don't need the same treatment. _Originally posted by @jolheiser in /gitea/gitea-docusaurus/issues/1#issuecomment-745440_
Member

I still think docs should live as close to the code as possible, so in the gitea repo, and imho this repo should also be merged into it, likely replacing the hugo build there?

I still think docs should live as close to the code as possible, so in the `gitea` repo, and imho this repo should also be merged into it, likely replacing the hugo build there?
Owner

This project will also build other tools' documentations, like tea or go-sdk.

This project will also build other tools' documentations, like tea or go-sdk.
Member

Then keep the markdown docs in those respective repos imho.

Then keep the markdown docs in those respective repos imho.
Owner

2 possiblility.

  • If one version will not changed on source code any more. Maybe the version's documentation should be removed from the docs site?
  • If one version will not changed on source code any more. Just copy all the docs content on this repository but it should also cannot be changed. It's a read copy. Both the source code repository and this repository have the documentation.
2 possiblility. - If one version will not changed on source code any more. Maybe the version's documentation should be removed from the docs site? - If one version will not changed on source code any more. Just copy all the docs content on this repository but it should also cannot be changed. It's a read copy. Both the source code repository and this repository have the documentation.
Author
Owner

Another thing to note about this, we just experienced a smaller taste of what could happen in the future.

Docusaurus v3 caused a change that affected every single version of our (supported) docs. Thankfully that was only 4 for now (main, 1.21, 1.20, and 1.19), however that may grow to some unknown number N depending on how old of docs we want to support. Also consider how this N may change depending on a possible future LTS intro.

Had the older docs been in this repo already, it would have been fewer PRs/branches to deal with. Again, thankfully the changes were also fairly minimal and largely consistent across the branches, but it still results in N amounts of work.

Another thing to note about this, we just experienced a smaller taste of what could happen in the future. Docusaurus v3 caused a change that affected every single version of our (supported) docs. Thankfully that was only 4 for now (main, 1.21, 1.20, and 1.19), however that may grow to some unknown number N depending on how old of docs we want to support. Also consider how this N may change depending on a possible future LTS intro. Had the older docs been in this repo already, it would have been fewer PRs/branches to deal with. Again, thankfully the changes were also fairly minimal and largely consistent across the branches, but it still results in N amounts of work.
Owner

Maybe we could have an archived documentation project and move all to that project and we can have a domain archived.docs.gitea.com. There is a link on docs.gitea.com to that new website. That's also what docusaurus did.
图片

Maybe we could have an archived documentation project and move all to that project and we can have a domain archived.docs.gitea.com. There is a link on docs.gitea.com to that new website. That's also what docusaurus did. ![图片](/attachments/26563efe-8ed6-4d18-a916-2c27a44579c3)
Sign in to join this conversation.
No Milestone
No Assignees
3 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: gitea/gitea-docusaurus#54
No description provided.