use git submodules for documentation content #331

caesar commented 2023年08月06日 02:02:08 +02:00

I like the idea of fully separating the documentation content from the website code, as proposed in #154.

Here's one way it could be done, using git submodules. I've used branches in the docs repo (currently https://codeberg.org/caesar/forgejo-docs/) for the different versions. I think this could be more maintainable than side-by-side directories.

However I'm not totally sure about the Git submodule approach as it requires the commit SHAs of the submodules to be committed to the parent repo, so updating the docs will still require committing to the website repo.

One way to avoid that might be to use a script to pull from the docs repo before build, instead of actually using Git submodules.
Perhaps someone with more experience with Git submodules has a better idea.

I should note that this is very much an experiment and I'm not totally committed to the idea. I can also see an advantage of keeping both code and content in the same repo, in cases where changes to the code might require updates to the documentation content.

Closes #154

Preview https://forgejo.codeberg.page/@pull_331/

I like the idea of fully separating the documentation content from the website code, as proposed in #154. Here's one way it could be done, using git submodules. I've used branches in the docs repo (currently https://codeberg.org/caesar/forgejo-docs/) for the different versions. I think this could be more maintainable than side-by-side directories. However I'm not totally sure about the Git submodule approach as it requires the commit SHAs of the submodules to be committed to the parent repo, so updating the docs will still require committing to the `website` repo. One way to avoid that might be to use a script to pull from the `docs` repo before build, instead of actually using Git submodules. Perhaps someone with more experience with Git submodules has a better idea. I should note that this is very much an experiment and I'm not totally committed to the idea. I can also see an advantage of keeping both code and content in the same repo, in cases where changes to the code might require updates to the documentation content. Closes #154 Preview https://forgejo.codeberg.page/@pull_331/

caesar commented 2023年08月06日 02:04:54 +02:00

The CI is giving a strange error: Host key verification failed when cloning the submodules. No idea why...

The CI is giving a strange error: `Host key verification failed` when cloning the submodules. No idea why...

earl-warren commented 2023年08月06日 06:11:33 +02:00

I like that the docs are in a single place at the moment as it allows me to focus on content. I see them as a temporary place where information can be collected and written in a way that is helpful to people. I link to the documentation when answering questions in the chat. I also update the documentation when I need to answer a question that has no answer in the documentation. Finally I use the documentation as a way to remember how things work when they get too complicated, such as Forgejo Actions.

Having the docs neatly separated in a content section where I do not have to worry about how it is presented is a welcome improvement. And I think it will help move the documentation to a proper framework with all the bells and whistles the reader expects when navigating them.

Restructuring them into multiple repositories is less appealing to me because it adds structure. This will be more effort for me when updating. Although I see some benefits in the proposed separation it feels like it could get in the way when moving to a documentation framework.

I like that the docs are in a single place at the moment as it allows me to focus on content. I see them as a temporary place where information can be collected and written in a way that is helpful to people. I link to the documentation when answering questions in the chat. I also update the documentation when I need to answer a question that has no answer in the documentation. Finally I use the documentation as a way to remember how things work when they get too complicated, such as Forgejo Actions. Having the docs neatly separated in a content section where I do not have to worry about how it is presented is a welcome improvement. And I think it will help move the documentation to a proper framework with all the bells and whistles the reader expects when navigating them. Restructuring them into multiple repositories is less appealing to me because it adds structure. This will be more effort for me when updating. Although I see some benefits in the proposed separation it feels like it could get in the way when moving to a documentation framework.

earl-warren commented 2023年08月06日 06:37:40 +02:00

The CI failure is because .gitmodules uses ssh url. You should use https urls that do not rely on ssh instead.

[submodule "docs-v1.19"]
	path = src/content/docs/v1.19
	url = git@codeberg.org:caesar/forgejo-docs.git
	branch = v1.19
[submodule "docs-v1.20"]
	path = src/content/docs/v1.20
	url = git@codeberg.org:caesar/forgejo-docs.git
	branch = v1.20

https://woodpecker-ci.org/docs/next/usage/pipeline-syntax#git-submodules

The CI failure is because .gitmodules uses ssh url. You should use https urls that do not rely on ssh instead. ``` [submodule "docs-v1.19"] path = src/content/docs/v1.19 url = git@codeberg.org:caesar/forgejo-docs.git branch = v1.19 [submodule "docs-v1.20"] path = src/content/docs/v1.20 url = git@codeberg.org:caesar/forgejo-docs.git branch = v1.20 ``` https://woodpecker-ci.org/docs/next/usage/pipeline-syntax#git-submodules

forgejo-website commented 2023年08月06日 11:20:16 +02:00

Preview ready: https://forgejo.codeberg.page/@pull_331/

Preview ready: https://forgejo.codeberg.page/@pull_331/

caesar commented 2023年08月06日 11:31:13 +02:00

A better presentation for the docs – either by moving to a dedicated framework or by implementing features directly – is a goal of mine (I'll open an issue later to discuss strategy).
I don't think this change of moving the docs content out of the website source repo will make a big difference either way to that. It is mostly just an organizational change that makes sense to me, especially to separate the issue trackers.
That said, now that the website repo history and issue tracker are already full of docs commits, maybe it's too late to sensibly and easily make this change.

To be honest, what I would prefer to see long term is for the docs content to live in the Forgejo source tree (as Gitea's docs do). I'd like the process to be more structured so that any time code changes are made that need documenting, the docs would be simultaneously updated.
However, I can see that this would be a challenge with the soft fork workflow, so I'm not particularly optimistic about it being implemented in the near future.

In the meantime I have no objection to just continuing as we are. This PR is more of a way to play with the idea proposed in #154 than something I actually want to see implemented right now.

A better presentation for the docs – either by moving to a dedicated framework or by implementing features directly – is a goal of mine (I'll open an issue later to discuss strategy). I don't think this change of moving the docs content out of the website source repo will make a big difference either way to that. It is mostly just an organizational change that makes sense to me, especially to separate the issue trackers. That said, now that the website repo history and issue tracker are already full of docs commits, maybe it's too late to sensibly and easily make this change. To be honest, what I would prefer to see long term is for the docs content to live in the Forgejo source tree (as Gitea's docs do). I'd like the process to be more structured so that any time code changes are made that need documenting, the docs would be simultaneously updated. However, I can see that this would be a challenge with the soft fork workflow, so I'm not particularly optimistic about it being implemented in the near future. In the meantime I have no objection to just continuing as we are. This PR is more of a way to play with the idea proposed in #154 than something I actually want to see implemented right now.

earl-warren commented 2023年08月06日 16:45:46 +02:00

That said, now that the website repo history and issue tracker are already full of docs commits, maybe it's too late to sensibly and easily make this change.

It is trivial to create a repository with just the commits that are related to the docs repository. I don't remember the name of the git extension that does this right now but it is a oneliner.

To be honest, what I would prefer to see long term is for the docs content to live in the Forgejo source tree (as Gitea's docs do). I'd like the process to be more structured so that any time code changes are made that need documenting, the docs would be simultaneously updated.
However, I can see that this would be a challenge with the soft fork workflow, so I'm not particularly optimistic about it being implemented in the near future.

Ideally yes. But the reality is that the dynamics of the documentation are entirely different than the code. In the vast majority of cases the person updating the documentation is not the person who implemented the feature / bug fix.

In the meantime I have no objection to just continuing as we are. This PR is more of a way to play with the idea proposed in #154 than something I actually want to see implemented right now.

I stated my reservations but I'm fine with the extra effort of having a separate repository if you feel this gives you more flexibility to improve the presentation.

> That said, now that the website repo history and issue tracker are already full of docs commits, maybe it's too late to sensibly and easily make this change. It is trivial to create a repository with just the commits that are related to the docs repository. I don't remember the name of the git extension that does this right now but it is a oneliner. > To be honest, what I would prefer to see long term is for the docs content to live in the Forgejo source tree (as Gitea's docs do). I'd like the process to be more structured so that any time code changes are made that need documenting, the docs would be simultaneously updated. > However, I can see that this would be a challenge with the soft fork workflow, so I'm not particularly optimistic about it being implemented in the near future. Ideally yes. But the reality is that the dynamics of the documentation are entirely different than the code. In the vast majority of cases the person updating the documentation is not the person who implemented the feature / bug fix. > In the meantime I have no objection to just continuing as we are. This PR is more of a way to play with the idea proposed in #154 than something I actually want to see implemented right now. I stated my reservations but I'm fine with the extra effort of having a separate repository if you feel this gives you more flexibility to improve the presentation.

👍 1

caesar commented 2023年08月12日 12:25:40 +02:00

Cross-posted from Matrix for visibility / archival:

I'm trying to decide on the ideal structure for the new docs repo (to contain only the content and be pulled into the website with Git submodules).

I'm using git-filter-repo to rewrite history and keep only the commits that affected the docs content.

I'd appreciate some input on the structure of the new repo. I'm thinking of doing what I already did in that PR: creating a separate branch for each version of the docs (v1.19, v1.20, v1.21 – maybe also latest and next could be branches that simply track the same head as the relevant version branches). One big advantage I see here is ease of backporting docs fixes to older versions by simply cherry-picking or even merging the same fix to both branches, git-flow-style.

But before I (ahem) commit to that structure, I'd appreciate input if anyone sees any major downsides or would prefer a different structure such as keeping all the versions in different directories on the same branch.

Cross-posted [from Matrix](https://matrix.to/#/!zpNKWqkiEOyljSMQDK:matrix.org/$jUMzTY3jW9fkoMWP5xGYBoS7siZch7r_zVOcZVVyuHQ) for visibility / archival: > I'm trying to decide on the ideal structure for the new `docs` repo (to contain only the content and be pulled into the website with Git submodules). > > I'm using [git-filter-repo](https://github.com/newren/git-filter-repo) to rewrite history and keep only the commits that affected the docs content. > > I'd appreciate some input on the structure of the new repo. I'm thinking of doing what I already did in that PR: creating a separate branch for each version of the docs (`v1.19`, `v1.20`, `v1.21` – maybe also `latest` and `next` could be branches that simply track the same head as the relevant version branches). One big advantage I see here is ease of backporting docs fixes to older versions by simply cherry-picking or even merging the same fix to both branches, `git-flow`-style. > > But before I (ahem) _commit_ to that structure, I'd appreciate input if anyone sees any major downsides or would prefer a different structure such as keeping all the versions in different directories on the same branch.

Ghost commented 2023年08月12日 14:45:57 +02:00

@earl-warren @Gusted since we've been the most active on the documentation lately, I propose to pause contributions for a few days so @caesar can work on the submodule separation without too much catching up with changes. It could be starting today or whenever @caesar says go.

@earl-warren @Gusted since we've been the most active on the documentation lately, I propose to pause contributions for a few days so @caesar can work on the submodule separation without too much catching up with changes. It could be starting today or whenever @caesar says go.

caesar commented 2023年08月12日 16:40:14 +02:00

Thanks @dachary, I was considering suggesting the same to reduce conflicts. I've already forked the docs so any changes from now I'll need to merge manually.

PRs could still be opened (ideally making changes to just one version of the docs) but just not merged, and I'll cherry-pick the changes.

I'll try and get this done today or tomorrow so as not to create too much of a backlog.

Thanks @dachary, I was considering suggesting the same to reduce conflicts. I've already forked the docs so any changes from now I'll need to merge manually. PRs could still be opened (ideally making changes to just one version of the docs) but just not merged, and I'll cherry-pick the changes. I'll try and get this done today or tomorrow so as not to create too much of a backlog.

earl-warren commented 2023年08月12日 16:46:26 +02:00

I'm fine refraining from documenting for a week.

I'm fine refraining from documenting for a week.

Ghost commented 2023年08月12日 17:29:13 +02:00

Same here.

Same here.

caesar commented 2023年08月14日 00:35:59 +02:00

I'd appreciate any feedback on the docs repo structure at caesar/forgejo-docs#1 if anyone has any suggestions.

I'd appreciate any feedback on the docs repo structure at https://codeberg.org/caesar/forgejo-docs/issues/1 if anyone has any suggestions.

caesar commented 2023年08月15日 16:43:31 +02:00

@earl-warren @Gusted since we've been the most active on the documentation lately, I propose to pause contributions for a few days so @caesar can work on the submodule separation without too much catching up with changes. It could be starting today or whenever @caesar says go.

I think forgejo/docs is ready for PRs to be opened there if there is documentation work to be done.

> @earl-warren @Gusted since we've been the most active on the documentation lately, I propose to pause contributions for a few days so @caesar can work on the submodule separation without too much catching up with changes. It could be starting today or whenever @caesar says go. I think [forgejo/docs](https://codeberg.org/forgejo/docs) is ready for PRs to be opened there if there is documentation work to be done.

caesar commented 2023年08月15日 17:25:09 +02:00

I think the only thing left to do before merging this is to sort out the CI (forgejo/docs#3).
If anyone has any suggestions let me know, otherwise I'll take a stab at it this evening hopefully.

I think the only thing left to do before merging this is to sort out the CI (forgejo/docs#3). If anyone has any suggestions let me know, otherwise I'll take a stab at it this evening hopefully.

crystal commented 2023年08月15日 17:47:01 +02:00

The URL to the submodule should be updated (to https://codeberg.org/forgejo/docs) before this is merged. Other than that, this is fine to merge now. Since contributions to the docs are frozen right now anyway, I don't think it would hurt to implement the CI stuff shortly after merging this. I will try to find some time to help out with this later today.

The URL to the submodule should be updated (to https://codeberg.org/forgejo/docs) before this is merged. Other than that, this is fine to merge now. Since contributions to the docs are frozen right now anyway, I don't think it would hurt to implement the CI stuff shortly after merging this. I will try to find some time to help out with this later today.

caesar commented 2023年08月15日 17:51:10 +02:00

The URL to the submodule should be updated

Thanks for the reminder!

> The URL to the submodule should be updated Thanks for the reminder!