Currently: Documentation upstreaming #277

fnetX commented 2022年11月05日 15:37:34 +01:00

Hello everyone,

during the hackathon these days, we're taking the effort to try and upstream this documentation.

This means:

• we are implementing a package that can be depended on by upstream Gitea to include the docs
• the docs are included within each instance's build and served there to match the current version
• this might mean changes to the licensing to sync with upstream Gitea docs (Apache 2.0 license)

The effort can be followed in: https://codeberg.org/Codeberg/Gitea-Documentation/

Hello everyone, during the hackathon these days, we're taking the effort to try and upstream this documentation. This means: - we are implementing a package that can be depended on by upstream Gitea to include the docs - the docs are included within each instance's build and served there to match the current version - this might mean changes to the licensing to sync with upstream Gitea docs (Apache 2.0 license) The effort can be followed in: https://codeberg.org/Codeberg/Gitea-Documentation/

svarmorsdrummen commented 2022年11月23日 03:40:12 +01:00

Codeberg/Documentation#277

Codeberg/Documentation#277

jklippel commented 2022年11月23日 20:43:04 +01:00

@svarmorsdrummen: Did you want to reference a different issue? (Why did you add the self-referencing link?)

@svarmorsdrummen: Did you want to reference a different issue? (Why did you add the self-referencing link?)

lhinderberger commented 2023年02月13日 15:04:24 +01:00

Since I've just stumbled upon this in a different context:

https://opensource.stackexchange.com/questions/12477/is-cc-by-sa-3-0-compatible-with-apache-2-0

I think this could be relevant for the upstreaming effort as well, even though Codeberg Docs uses CC-BY-SA 4.0. Gitea and Forgejo docs are, if I'm not mistaken, licensed under Apache-2.0, which could mean that it's impossible (or at least risky) to combine both.

So documentation upstreaming might require relicensing either Codeberg docs to Apache-2.0/CC-BY or Forgejo Docs to to CC-BY-SA (caveat: Forgejo itself is MIT-licensed and the docs are part of its source tree, so that might open up an entirely different can of worms). But unless there's a CLA that I don't know about, asking each contributor for permission would be a big effort at this point.

I don't know a good solution to this. For my own project, I plan on refraining from the use of CC-BY-SA and instead use Apache-2.0 throughout the whole project, which in that context seems like a good fit (and, at this point, is still feasible 🙈). YMMV.

As always when I talk about licenses and copyright: I am not a lawyer and this is not legal advice.

Since I've just stumbled upon this in a different context: https://opensource.stackexchange.com/questions/12477/is-cc-by-sa-3-0-compatible-with-apache-2-0 I think this could be relevant for the upstreaming effort as well, even though Codeberg Docs uses CC-BY-SA 4.0. Gitea and Forgejo docs are, if I'm not mistaken, licensed under Apache-2.0, which could mean that it's impossible (or at least risky) to combine both. So documentation upstreaming might require relicensing either Codeberg docs to Apache-2.0/CC-BY or Forgejo Docs to to CC-BY-SA (caveat: Forgejo itself is MIT-licensed and the docs are part of its source tree, so that might open up an entirely different can of worms). But unless there's a CLA that I don't know about, asking each contributor for permission would be a big effort at this point. I don't know a good solution to this. For my own project, I plan on refraining from the use of CC-BY-SA and instead use Apache-2.0 throughout the whole project, which in that context seems like a good fit (and, at this point, is still feasible 🙈). YMMV. As always when I talk about licenses and copyright: I am not a lawyer and this is not legal advice.

Ghost commented 2023年02月16日 10:20:57 +01:00

Forgejo needs documentation and I'd like to build upon Codeberg documentation to do so. The upside is that, in addition to having existing end-user content, the tooling is in place and the effort to make it into an independent package was bootstrapped.

My focus will be on adding sections that are not relevant to Codeberg but required for Forgejo:

• Installation
• Upgrade
• Internal CI/CD

And the release notes which matter to both Forgejo and Codeberg when it comes to user facing features or bug fixes.

What I'm unsure about is how to go about doing that since it can be argued it is out of scope and that Forgejo should build its documentation independently and borrow from the Codeberg documentation rather than trying to contribute to it.

What do you think?

Forgejo [needs documentation](https://codeberg.org/forgejo/meta/issues/67) and I'd like to build upon Codeberg documentation to do so. The upside is that, in addition to having existing end-user content, the tooling is in place and [the effort to make it into an independent package](https://codeberg.org/Codeberg/Gitea-Documentation/) was bootstrapped. My focus will be on adding sections that are not relevant to Codeberg but required for Forgejo: * Installation * Upgrade * Internal CI/CD And the release notes which matter to both Forgejo and Codeberg when it comes to user facing features or bug fixes. What I'm unsure about is how to go about doing that since it can be argued it is out of scope and that Forgejo should build its documentation independently and borrow from the Codeberg documentation rather than trying to contribute to it. What do you think?

fnetX commented 2023年02月24日 21:01:04 +01:00

The current state is that with the creation of Forgejo, there is no longer a clear direction for us.

The goal should IMHO still be to combine the forces and help with good Forgejo end-user docs based on what Codeberg already offers, but given some disagreement between collaborators, I will not push this forward personally.

The current state is that with the creation of Forgejo, there is no longer a clear direction for us. The goal should IMHO still be to combine the forces and help with good Forgejo end-user docs based on what Codeberg already offers, but given some disagreement between collaborators, I will not push this forward personally.

lhinderberger commented 2023年02月25日 11:59:30 +01:00

Maybe keep all Codeberg-related (+ possibly onboarding/Getting Started) docs here and link to built-in Forgejo docs (once they are ready) for everything else?

Maybe keep all Codeberg-related (+ possibly onboarding/Getting Started) docs here and link to built-in Forgejo docs (once they are ready) for everything else?

fnetX commented 2023年06月23日 03:05:29 +02:00

This project went stale. However, the Forgejo team now maintains a documentation, and synching with them makes a lot of sense. Should be discussed in a fresh issue, though.

This project went stale. However, the Forgejo team now maintains a documentation, and synching with them makes a lot of sense. Should be discussed in a fresh issue, though.

Ghost commented 2023年06月23日 09:53:49 +02:00

The documentation is at https://codeberg.org/forgejo/website/src/branch/main/src/pages/docs and is actively maintained. It is bare bones in terms of layout: this is almost 100% content, with just a URL to the source from which it is paired / sync when appropriate.

That absolutely does not solve many of the issue discussed here. But it certainly solves one major issue: having updated content 😄

The documentation is at https://codeberg.org/forgejo/website/src/branch/main/src/pages/docs and is actively maintained. It is bare bones in terms of layout: this is almost 100% content, with just a URL to the source from which it is paired / sync when appropriate. That absolutely does not solve many of the issue discussed here. But it certainly solves one major issue: having updated content 😄