URL strategy for documentation #154

Ryuno-Ki commented 2023年03月07日 14:02:15 +01:00

This is something I brought up in the governance meeting at forgejo/meta#166 while we had time.

As it currently stands, the https://codeberg.org/forgejo-contrib/docs appears to be moved into the website (my understanding. Haven't compared in detail yet).

I can see some issues with the current structure.

For one, the version is part of the URL. This means, once v1.20 is released, v1.19 is to be EOLed (assuming forgejo/meta#156 will be reflected). To me, this means, that the documentation for v1.19 is also deprecated.

Then, because the URL is part of the URL, the files have to be copied over to v1.20. That means, we have duplicated content which might cause its own set of problems.

I'd rather use tags (like in https://www.11ty.dev/docs/data-eleventy-supplied/#fileslug ) to indicate when a change was introduced and remove the version from the URL.
This way, we only have one living documentation that can be updated without the copying overhead.

Also, there's a lot of documentation to maintain on the website. Given that those files are basically Markdown with some Frontmatter that is important to Astro we might as well use git submodules to pull in the changes.

This is something I brought up in the governance meeting at https://codeberg.org/forgejo/meta/issues/166 while we had time. As it currently stands, the https://codeberg.org/forgejo-contrib/docs appears to be moved into the website (my understanding. Haven't compared in detail yet). I can see some issues with the current structure. For one, the version is part of the URL. This means, once v1.20 is released, v1.19 is to be EOLed (assuming https://codeberg.org/forgejo/meta/issues/156 will be reflected). To me, this means, that the documentation for v1.19 is also deprecated. Then, because the URL is part of the URL, the files have to be copied over to v1.20. That means, we have duplicated content which [might cause its own set of problems](https://moz.com/learn/seo/duplicate-content). I'd rather use tags (like in https://www.11ty.dev/docs/data-eleventy-supplied/#fileslug ) to indicate when a change was introduced and remove the version from the URL. This way, we only have one living documentation that can be updated without the copying overhead. Also, there's a lot of documentation to maintain on the website. Given that those files are basically Markdown with some Frontmatter that is important to Astro we might as well use git submodules to pull in the changes.

Ghost commented 2023年03月07日 17:52:23 +01:00

Please propose a PR with these changes, I'm in favor.

Please propose a PR with these changes, I'm in favor.

Ryuno-Ki commented 2023年03月07日 20:02:36 +01:00

I'd like to get the opinion on @crystal and @earl-warren first before moving forward on this. They have contributed PRs to the website as well in recent times.

I'd like to get the opinion on @crystal and @earl-warren first before moving forward on this. They have contributed PRs to the website as well in recent times.

crystal commented 2023年03月07日 20:20:17 +01:00

I'm confused about what exactly is being proposed in the OP, but I am in favor of moving the docs to a different repo and pulling them in as a submodule. Different versions of the documentation can be pulled in as multiple submodules so we can support the docs for the latest version as well as any LTS versions or other versions we decide to continue supporting.

I'm confused about what exactly is being proposed in the OP, but I am in favor of moving the docs to a different repo and pulling them in as a submodule. Different versions of the documentation can be pulled in as multiple submodules so we can support the docs for the latest version as well as any LTS versions or other versions we decide to continue supporting.

Ryuno-Ki commented 2023年03月08日 15:28:17 +01:00

Okay, that works for me.

I might get back to you for work on woodpecker (never touched it, but have interest in learning about it, because it would help me with other projects I have).

Okay, that works for me. I might get back to you for work on woodpecker (never touched it, but have interest in learning about it, because it would help me with other projects I have).

earl-warren commented 2023年03月08日 15:56:18 +01:00

I'm in favor.

I'm in favor.

Ryuno-Ki commented 2023年03月08日 18:14:28 +01:00

Okay, as I feared, it won't be straight forward anymore 😨

cd src/pages
git submodule add https://codeberg.org/forgejo-contrib/docs.git

fails with

fatal: 'src/pages/docs' already exists in the index

What would be needed is to remove this directory from git before it can be added as submodule. https://stackoverflow.com/a/12902857

Given that we already have PRs merged, I feel it's not worth the effort.

---

What can be done is defining an alias:

cd src/pages
git submodule add https://codeberg.org/forgejo-contrib/docs.git documentation

If not present, the project root needs to have a (possibly empty) .gitmodules file for this to succeed.

Then the changes could be moved into the contrib repository. I don't see a native rename subcommand, but according to https://stackoverflow.com/a/18712756 a git mv should work (appears to be on my machine).

How do we want to proceed?

Okay, as I feared, it won't be straight forward anymore 😨 ```sh cd src/pages git submodule add https://codeberg.org/forgejo-contrib/docs.git ``` fails with > fatal: 'src/pages/docs' already exists in the index What would be needed is to remove this directory from git before it can be added as submodule. https://stackoverflow.com/a/12902857 Given that we already have PRs merged, I feel it's not worth the effort. --- What can be done is defining an alias: ```sh cd src/pages git submodule add https://codeberg.org/forgejo-contrib/docs.git documentation ``` If not present, the project root needs to have a (possibly empty) `.gitmodules` file for this to succeed. Then the changes could be moved into the contrib repository. I don't see a native rename subcommand, but according to https://stackoverflow.com/a/18712756 a `git mv` should work (appears to be on my machine). How do we want to proceed?

Ghost commented 2023年03月08日 19:14:09 +01:00

If you're not comfortable working with submodules maybe this should be dealt with by someone else? It's not difficult but (as often with git) it is not straightforward either 😄

If you're not comfortable working with submodules maybe this should be dealt with by someone else? It's not difficult but (as often with git) it is not straightforward either 😄

Ryuno-Ki commented 2023年03月08日 22:09:11 +01:00

I'd welcome that.

I only had contact with git submodules once or twice. The last time is years ago.
It's not easy to recall how I did things back in the day.

I'd welcome that. I only had contact with git submodules once or twice. The last time is years ago. It's not easy to recall how I did things back in the day.