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

New Issue

jolheiser · 2023-07-28T00:28:41Z

jolheiser commented

2023-07-28 00:28:41 +00:00

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_

👍 2

jolheiser referenced this issue

2023-07-28 00:30:14 +00:00

Process #1

silverwind commented

2023-07-30 23:35:13 +00:00

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?

lunny commented

2023-07-31 00:36:12 +00:00

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

silverwind commented

2023-07-31 09:59:56 +00:00

Then keep the markdown docs in those respective repos imho.

lunny commented

2023-10-19 08:37:42 +00:00

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.

jolheiser commented

2023-11-20 14:51:58 +00:00

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.

👍 1

lunny commented

2023-11-21 01:50:02 +00:00

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)

图片.png

33 KiB

This repo is archived. You cannot comment on issues.