[DOCS] CONTRIBUTING
Refs: https://codeberg.org/forgejo/forgejo/issues/8 Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/153 Refs: https://codeberg.org/forgejo/forgejo/issues/123 Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/299 (cherry picked from commit08dcef0c8c) [DOCS] CONTRIBUTING/RELEASE: https://forgejo.org/docs/admin Because the version is not displayed on the landing page of Forgejo, there cannot be a link to a versionned documentation. There must exist a link that points to the latest version on the website for the forgejo instance to display. Better but more complicated approaches could be to: * Embed the documentation in Forgejo * Allow the admin to not display the help * Allow the admin to display a versionned help or not (cherry picked from commit83cc389239) (cherry picked from commit5df52b8a4f) (cherry picked from commit9a66b3d70b) [DOCS] CONTRIBUTING/RELEASE: reminder to update FORGEJO_VERSION (cherry picked from commit2a4d0bd164) (cherry picked from commitd68576ba67) [DOCS] CONTRIBUTING: updates * Remove obsolete description of the well being & moderation team and replace them with a link to the moderation email. * Remove description of the governance process and replace with a link to the governance readme that did not exist at the time. * Add links to the Forgejo documentation (cherry picked from commitdf749da272) (cherry picked from commit4da39128c5) (cherry picked from commitf442ca6f40) (cherry picked from commit031928c447) (cherry picked from commit1e6ba47216) (cherry picked from commit8916a1f8c6) (cherry picked from commit663e28c412)
This commit is contained in:
Loïc Dachary
Earl Warren
parent
5098f1224b
commit
d56b130baa
8 changed files with 421 additions and 0 deletions
24
CONTRIBUTING.md
Normal file
24
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,24 @@
|
||||||
|
# Forgejo Contributor Guide
|
||||||
|
|
||||||
|
The Forgejo project is run by a community of people who are expected to follow this guide when cooperating on a simple bug fix as well as when changing the governance. For more information about the project, take a look at [the documentation explaining what Forgejo provides](README.md).
|
||||||
|
|
||||||
|
Sensitive security-related issues should be reported to [security@forgejo.org](mailto:security@forgejo.org) using [encryption](https://keyoxide.org/security@forgejo.org).
|
||||||
|
|
||||||
|
## For everyone involved
|
||||||
|
|
||||||
|
- [Documentation](https://forgejo.org/docs/latest/)
|
||||||
|
- [Code of Conduct](CONTRIBUTING/COC.md)
|
||||||
|
- [Bugs, features, security and others discussions](CONTRIBUTING/DISCUSSIONS.md)
|
||||||
|
- [Governance](CONTRIBUTING/GOVERNANCE.md)
|
||||||
|
- [Sustainability and funding](https://codeberg.org/forgejo/sustainability/src/branch/master/README.md)
|
||||||
|
|
||||||
|
## For contributors
|
||||||
|
|
||||||
|
- [Developer Certificate of Origin (DCO)](CONTRIBUTING/DCO.md)
|
||||||
|
- [Development workflow](CONTRIBUTING/WORKFLOW.md)
|
||||||
|
|
||||||
|
## For maintainers
|
||||||
|
|
||||||
|
- [Release management](CONTRIBUTING/RELEASE.md)
|
||||||
|
- [Secrets](CONTRIBUTING/SECRETS.md)
|
||||||
|
|
||||||
3
CONTRIBUTING/COC.md
Normal file
3
CONTRIBUTING/COC.md
Normal file
|
|
@ -0,0 +1,3 @@
|
||||||
|
# Code of Conduct and Moderation team
|
||||||
|
|
||||||
|
Forgejo strives to be an inclusive project where everyone can participate in a safe environment. If a Forgejo community member feels unsafe for any reason, the **Moderation team** is available at `moderation@forgejo.org` and will put a stop to actions that are contrary to the [Code of Conduct](https://codeberg.org/forgejo/code-of-conduct) or the law.
|
||||||
29
CONTRIBUTING/DCO.md
Normal file
29
CONTRIBUTING/DCO.md
Normal file
|
|
@ -0,0 +1,29 @@
|
||||||
|
# Developer Certificate of Origin (DCO)
|
||||||
|
|
||||||
|
Contributions to Forgejo, in all the repositories in the [Forgejo organization](https://codeberg.org/forgejo) are accepted provided the author agrees to the following Developer Certificate of Origin (DCO).
|
||||||
|
|
||||||
|
```
|
||||||
|
By making a contribution to Forgejo, I certify that:
|
||||||
|
|
||||||
|
(a) The contribution was created in whole or in part by me and I
|
||||||
|
have the right to submit it under the Free Software license
|
||||||
|
indicated in the file; or
|
||||||
|
|
||||||
|
(b) The contribution is based upon previous work that, to the best
|
||||||
|
of my knowledge, is covered under an appropriate Free Software
|
||||||
|
license and I have the right under that license to submit that
|
||||||
|
work with modifications, whether created in whole or in part
|
||||||
|
by me, under the same Free Software license (unless I am
|
||||||
|
permitted to submit under a different license), as indicated
|
||||||
|
in the file; or
|
||||||
|
|
||||||
|
(c) The contribution was provided directly to me by some other
|
||||||
|
person who certified (a), (b) or (c) and I have not modified
|
||||||
|
it.
|
||||||
|
|
||||||
|
(d) I understand and agree that this project and the contribution
|
||||||
|
are public and that a record of the contribution (including all
|
||||||
|
personal information I submit with it, including my sign-off) is
|
||||||
|
maintained indefinitely and may be redistributed consistent with
|
||||||
|
this project or the Free Software license(s) involved.
|
||||||
|
```
|
||||||
18
CONTRIBUTING/DISCUSSIONS.md
Normal file
18
CONTRIBUTING/DISCUSSIONS.md
Normal file
|
|
@ -0,0 +1,18 @@
|
||||||
|
# Bugs, features and discussions
|
||||||
|
|
||||||
|
The [Forgejo issue tracker](https://codeberg.org/forgejo/forgejo/issues) is where **bugs** should be reported and **features** requested.
|
||||||
|
|
||||||
|
Dedicated repositories in the [Forgejo organization](https://codeberg.org/forgejo) cover areas such as:
|
||||||
|
- the [website](https://codeberg.org/forgejo/website)
|
||||||
|
- the [Code of Conduct](https://codeberg.org/forgejo/code-of-conduct)
|
||||||
|
- the [sustainability and funding](https://codeberg.org/forgejo/sustainability).
|
||||||
|
|
||||||
|
Other discussions regarding all **non technical aspects** of Forgejo, such as the governance, happen in a dedicated [issue tracker](https://codeberg.org/forgejo/discussions/issues) and in the [matrix chatroom](https://matrix.to/#/#forgejo-chat:matrix.org).
|
||||||
|
|
||||||
|
# Security
|
||||||
|
|
||||||
|
The [security team](https://codeberg.org/forgejo/meta/src/branch/readme/TEAMS.md#security) takes care of security vulnerabilities. It handles sensitive security-related issues reported to [security@forgejo.org](mailto:security@forgejo.org) using [encryption](https://keyoxide.org/security@forgejo.org).
|
||||||
|
|
||||||
|
The security team also keeps the content of the [security.txt](https://codeberg.org/forgejo/website/src/branch/main/public/.well-known/security.txt) file up to date.
|
||||||
|
|
||||||
|
The private GPG key for `security@forgejo.org` is shared among all members of the security team and not stored online.
|
||||||
9
CONTRIBUTING/GOVERNANCE.md
Normal file
9
CONTRIBUTING/GOVERNANCE.md
Normal file
|
|
@ -0,0 +1,9 @@
|
||||||
|
# Governance
|
||||||
|
|
||||||
|
## Codeberg e.V. custodian of the domains
|
||||||
|
|
||||||
|
The Forgejo [domains](https://codeberg.org/forgejo/meta/issues/41) are owned by the democratic non-profit dedicated to Free Software [Codeberg e.V.](https://codeberg.org/Codeberg/org/src/branch/main/en/bylaws.md). Forgejo is therefore ultimately under the control of Codeberg e.V. and its governance. However, although Codeberg e.V. is committed to use and host Forgejo, it is expected that Forgejo defines its own governance, in a way that is compatible with the Codeberg e.V. governance.
|
||||||
|
|
||||||
|
## Forgejo Governance
|
||||||
|
|
||||||
|
Forgejo was bootstraped in November 2022 and [defined its governance](https://codeberg.org/forgejo/governance/src/branch/main/README.md) in the following months.
|
||||||
158
CONTRIBUTING/RELEASE.md
Normal file
158
CONTRIBUTING/RELEASE.md
Normal file
|
|
@ -0,0 +1,158 @@
|
||||||
|
# Release management
|
||||||
|
|
||||||
|
## Release numbering
|
||||||
|
|
||||||
|
The Forgejo release numbers are composed of the Gitea release number followed by a dash and a serial number. For instance:
|
||||||
|
|
||||||
|
* Gitea **v1.18.0** will be Forgejo **v1.18.0-0**, **v1.18.0-1**, etc
|
||||||
|
|
||||||
|
The Gitea release candidates are suffixed with **-rcN** which is handled as a special case for packaging: although **X.Y.Z** is lexicographically lower than **X.Y.Z-rc1** is is considered greater. The Forgejo serial number must therefore be inserted before the **-rcN** suffix to preserve the expected version ordering.
|
||||||
|
|
||||||
|
* Gitea **v1.18.0-rc0** will be Forgejo **v1.18.0-0-rc0**, **v1.18.0-1-rc0**
|
||||||
|
* Gitea **v1.18.0-rc1** will be Forgejo **v1.18.0-2-rc1**, **v1.18.0-3-rc1**, **v1.18.0-4-rc1**
|
||||||
|
* Gitea **v1.18.0** will be Forgejo **v1.18.0-5**, **v1.18.0-6**, **v1.18.0-7**
|
||||||
|
* etc.
|
||||||
|
|
||||||
|
Because Forgejo is a soft fork of Gitea, it must retain the same release numbering scheme to be compatible with libraries and tools that depend on it. For instance, the tea CLI or the Gitea SDK will behave differently depending on the server version they connect to. If Forgejo had a different numbering scheme, it would no longer be compatible with the Gitea ecosystem.
|
||||||
|
|
||||||
|
From a [Semantic Versioning](https://semver.org/) standpoint, all Forgejo releases are [pre-releases](https://semver.org/#spec-item-9) because they are suffixed with a dash. They are syntactically correct but do not comply with the Semantic Versioning recommendations. Gitea is not compliant either and as long as Forgejo is a soft fork, it inherits this problem.
|
||||||
|
|
||||||
|
## Release process
|
||||||
|
|
||||||
|
When publishing the vX.Y.Z-N release, the following steps must be followed:
|
||||||
|
|
||||||
|
### Semantic version
|
||||||
|
|
||||||
|
* Update the FORGEJO_VERSION variable in the Makefile
|
||||||
|
|
||||||
|
### Create a milestone and a check list
|
||||||
|
|
||||||
|
* Create a `Forgejo vX.X.Z-N` milestone set to the date of the release
|
||||||
|
* Create an issue named `[RELEASE] Forgejo vX.Y.Z-N` with a description that includes a list of what needs to be done for the release with links to follow the progress
|
||||||
|
* Set the milestone of this issue to `Forgejo vX.X.Z-N`
|
||||||
|
* Close the milestone when the release is complete
|
||||||
|
|
||||||
|
### Cherry pick the latest commits from Gitea
|
||||||
|
|
||||||
|
The vX.Y/forgejo branch is populated as part of the [rebase on top of Gitea](WORKFLOW.md). The release happens in between rebase and it is worth checking if the matching Gitea branch, release/vX.Y contains commits that should be included in the release.
|
||||||
|
|
||||||
|
* `cherry-pick -x` the commits
|
||||||
|
* push the vX.Y/forgejo branch including the commits
|
||||||
|
* verify that the tests pass
|
||||||
|
|
||||||
|
### Release Notes
|
||||||
|
|
||||||
|
* Add an entry in RELEASE-NOTES.md
|
||||||
|
* Copy/paste the matching entry from CHANGELOG.md
|
||||||
|
* Update the PR references prefixing them with https://github.com/go-gitea/gitea/pull/
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
|
||||||
|
When Forgejo is released, artefacts (packages, binaries, etc.) are first published by the CI/CD pipelines in the https://codeberg.org/forgejo-experimental organization, to be downloaded and verified to work.
|
||||||
|
|
||||||
|
* Push the vX.Y/forgejo branch to https://codeberg.org/forgejo-integration/forgejo
|
||||||
|
* Push the vX.Y.Z-N tag to https://codeberg.org/forgejo-integration (if it fails for whatever reason, the tag and the release can be removed manually)
|
||||||
|
* Binaries are built and uploaded to https://codeberg.org/forgejo/forgejo-integration/releases
|
||||||
|
* Container images are built and uploaded to https://codeberg.org/forgejo-integration/-/packages/container/forgejo/versions
|
||||||
|
* Push the vX.Y/forgejo branch to https://codeberg.org/forgejo-experimental/forgejo
|
||||||
|
* Push the vX.Y/forgejo branch to https://codeberg.org/forgejo/experimental
|
||||||
|
* Push the vX.Y.Z-N tag to https://codeberg.org/forgejo/experimental
|
||||||
|
* Binaries are downloaded from https://codeberg.org/forgejo-integration, signed and copied to https://codeberg.org/forgejo-experimental
|
||||||
|
* Container images are copied from https://codeberg.org/forgejo-integration to https://codeberg.org/forgejo-experimental
|
||||||
|
* Fetch the Forgejo release as part of the [forgejo-ci](https://codeberg.org/Codeberg-Infrastructure/scripted-configuration/src/branch/main/hosts/forgejo-ci) test suite. Push the change to a branch of a repository enabled in https://ci.dachary.org/ ([read more...](https://codeberg.org/forgejo/forgejo/issues/208)). It will deploy the release and run high level integration tests.
|
||||||
|
* Reach out to packagers and users to manually verify the release works as expected
|
||||||
|
|
||||||
|
### Publication
|
||||||
|
|
||||||
|
* Push the vX.Y.Z-N tag to https://codeberg.org/forgejo/release
|
||||||
|
* Binaries are downloaded from https://codeberg.org/forgejo-integration, signed and copied to https://codeberg.org/forgejo
|
||||||
|
* Container images are copied from https://codeberg.org/forgejo-integration to https://codeberg.org/forgejo
|
||||||
|
|
||||||
|
### Website update
|
||||||
|
|
||||||
|
* Restart the last CI build at https://codeberg.org/forgejo/website/src/branch/main/
|
||||||
|
* Verify https://forgejo.org/download/ points to the expected release
|
||||||
|
* Update the [documentation link to the latest version](https://codeberg.org/forgejo/website/src/commit/e63c6f8ab64876b10b86de1d18162b6ccb87bd99/.woodpecker.yml#L35)
|
||||||
|
* Manually try the instructions to work
|
||||||
|
|
||||||
|
### DNS update
|
||||||
|
|
||||||
|
* Update the `release.forgejo.org` TXT record that starts with `forgejo_versions=` to be `forgejo_versions=vX.Y.Z-N`
|
||||||
|
|
||||||
|
### Standard toot
|
||||||
|
|
||||||
|
The following toot can be re-used to announce a minor release at `https://floss.social/@forgejo`. For more significant releases it is best to consider a dedicated and non-standard toot.
|
||||||
|
|
||||||
|
```
|
||||||
|
#Forgejo vX.Y.Z-N was just released! This is a minor patch. Check out the release notes and download it at https://forgejo.org/releases/. If you experience any issues with this release, please report to https://codeberg.org/forgejo/forgejo/issues.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Release signing keys management
|
||||||
|
|
||||||
|
A GPG master key with no expiration date is created and shared with members of the Owners team via encrypted email. A subkey with a one year expiration date is created and stored in the secrets repository, to be used by the CI pipeline. The public master key is stored in the secrets repository and published where relevant.
|
||||||
|
|
||||||
|
### Master key creation
|
||||||
|
|
||||||
|
* gpg --expert --full-generate-key
|
||||||
|
* key type: ECC and ECC option with Curve 25519 as curve
|
||||||
|
* no expiration
|
||||||
|
* id: Forgejo Releases <contact@forgejo.org>
|
||||||
|
* gpg --export-secret-keys --armor EB114F5E6C0DC2BCDD183550A4B61A2DC5923710 and send via encrypted email to Owners
|
||||||
|
* gpg --export --armor EB114F5E6C0DC2BCDD183550A4B61A2DC5923710 > release-team-gpg.pub
|
||||||
|
* commit to the secret repository
|
||||||
|
|
||||||
|
### Subkey creation and renewal
|
||||||
|
|
||||||
|
* gpg --expert --edit-key EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
|
||||||
|
* addkey
|
||||||
|
* key type: ECC (signature only)
|
||||||
|
* key validity: one year
|
||||||
|
* create [an issue](https://codeberg.org/forgejo/forgejo/issues) to schedule the renewal
|
||||||
|
|
||||||
|
#### 2023
|
||||||
|
|
||||||
|
* gpg --export --armor F7CBF02094E7665E17ED6C44E381BF3E50D53707 > 2023-release-team-gpg.pub
|
||||||
|
* gpg --export-secret-keys --armor F7CBF02094E7665E17ED6C44E381BF3E50D53707 > 2023-release-team-gpg
|
||||||
|
* commit to the secrets repository
|
||||||
|
* renewal issue https://codeberg.org/forgejo/forgejo/issues/58
|
||||||
|
|
||||||
|
### CI configuration
|
||||||
|
|
||||||
|
In the Woodpecker CI configuration the following secrets must be set:
|
||||||
|
|
||||||
|
* `releaseteamgpg` is the secret GPG key used to sign the releases
|
||||||
|
* `releaseteamuser` is the user name to authenticate with the Forgejo API and publish the releases
|
||||||
|
* `releaseteamtoken` is the token to authenticate `releaseteamuser` with the Forgejo API and publish the releases
|
||||||
|
* `domain` is `codeberg.org`
|
||||||
|
|
||||||
|
## Users, organizations and repositories
|
||||||
|
|
||||||
|
### Shared user: release-team
|
||||||
|
|
||||||
|
The [release-team](https://codeberg.org/release-team) user publishes and signs all releases. The associated email is mailto:release@forgejo.org.
|
||||||
|
|
||||||
|
The public GPG key used to sign the releases is [EB114F5E6C0DC2BCDD183550A4B61A2DC5923710](https://codeberg.org/release-team.gpg) `Forgejo Releases <release@forgejo.org>`
|
||||||
|
|
||||||
|
### Shared user: forgejo-ci
|
||||||
|
|
||||||
|
The [forgejo-ci](https://codeberg.org/forgejo-ci) user is dedicated to https://forgejo-ci.codeberg.org/ and provides it with OAuth2 credentials it uses to run.
|
||||||
|
|
||||||
|
### Shared user: forgejo-experimental-ci
|
||||||
|
|
||||||
|
The [forgejo-experimental-ci](https://codeberg.org/forgejo-experimental-ci) user is dedicated to provide the application tokens used by Woodpecker CI repositories to build releases and publish them to https://codeberg.org/forgejo-experimental. It does not (and must not) have permission to publish releases at https://codeberg.org/forgejo.
|
||||||
|
|
||||||
|
### Integration and experimental organization
|
||||||
|
|
||||||
|
The https://codeberg.org/forgejo-integration organization is dedicated to integration testing. Its purpose is to ensure all artefacts can effectively be published and retrieved by the CI/CD pipelines.
|
||||||
|
|
||||||
|
The https://codeberg.org/forgejo-experimental organization is dedicated to publishing experimental Forgejo releases. They are copied from the https://codeberg.org/forgejo-integration organization.
|
||||||
|
|
||||||
|
The `forgejo-experimental-ci` user as well as all Forgejo contributors working on the CI/CD pipeline should be owners of both organizations.
|
||||||
|
|
||||||
|
The https://codeberg.org/forgejo-integration/forgejo repository is coupled with a Woodpecker CI repository configured with the credentials provided by the https://codeberg.org/forgejo-experimental-ci user. It runs the pipelines found in `releases/woodpecker-build/*.yml` which builds and publishes an unsigned release in https://codeberg.org/forgejo-integration.
|
||||||
|
|
||||||
|
### Experimental and release repositories
|
||||||
|
|
||||||
|
The https://codeberg.org/forgejo/experimental private repository is coupled with a Woodpecker CI repository configured with the credentials provided by the https://codeberg.org/forgejo-experimental-ci user. It runs the pipelines found in `releases/woodpecker-publish/*.yml` which signs and copies a release from https://codeberg.org/forgejo-integration into https://codeberg.org/forgejo-experimental.
|
||||||
|
|
||||||
|
The https://codeberg.org/forgejo/release private repository is coupled with a Woodpecker CI repository configured with the credentials provided by the https://codeberg.org/release-team user. It runs the pipelines found in `releases/woodpecker-publish/*.yml` which signs and copies a release from https://codeberg.org/forgejo-integration into https://codeberg.org/forgejo.
|
||||||
56
CONTRIBUTING/SECRETS.md
Normal file
56
CONTRIBUTING/SECRETS.md
Normal file
|
|
@ -0,0 +1,56 @@
|
||||||
|
# Secrets
|
||||||
|
|
||||||
|
All Forgejo credentials are shared among the [secret keepers](https://codeberg.org/forgejo/meta/src/branch/readme/TEAMS.md#secrets-keeper) teams in a private repository with encrypted content.
|
||||||
|
|
||||||
|
## Get started
|
||||||
|
|
||||||
|
1. Make sure you have a GPG Key, or [create one](https://github.com/NicoHood/gpgit#12-key-generation)
|
||||||
|
2. Send someone else your public key and ask this person to add yourself as a recipient
|
||||||
|
```
|
||||||
|
# Commands for the other person
|
||||||
|
$ gpg --import public_key.asc
|
||||||
|
# The following command will open a prompt, with the available public keys.
|
||||||
|
# Choose the one you just added and all secrets will be re-encrypted with this new key.
|
||||||
|
$ gopass recipients add
|
||||||
|
```
|
||||||
|
3. [Install gopass](https://www.gopass.pw/#install)
|
||||||
|
> :warning: When installing on Ubuntu or Debian you can either download the deb package, install manually or build from source or use our APT repository ([github comment](https://github.com/gopasspw/gopass/issues/1849#issuecomment-802789285) with more information).
|
||||||
|
4. Clone this repo using `gopass` (the name and email are for `git config`)
|
||||||
|
```
|
||||||
|
$ gopass clone git@codeberg.org:forgejo/gopass.git
|
||||||
|
```
|
||||||
|
5. Check the consistency of the gopass storage
|
||||||
|
```
|
||||||
|
$ gopass fsck
|
||||||
|
```
|
||||||
|
|
||||||
|
## Get a secret
|
||||||
|
|
||||||
|
Show the whole secret file:
|
||||||
|
```
|
||||||
|
$ gopass show ovh.com/manager
|
||||||
|
```
|
||||||
|
|
||||||
|
Copy the password in the clipboard:
|
||||||
|
```
|
||||||
|
$ gopass show -c ovh.com/manager
|
||||||
|
```
|
||||||
|
|
||||||
|
Copy the `user` part of the secret in the clipboard:
|
||||||
|
```
|
||||||
|
$ gopass show -c ovh.com/manager user
|
||||||
|
```
|
||||||
|
|
||||||
|
## Insert or edit a secret
|
||||||
|
```
|
||||||
|
$ gopass edit ovh.com/manager
|
||||||
|
```
|
||||||
|
In the editor, insert the password on the first line.
|
||||||
|
You may then add lines with a `key: value` syntax (`user: username` for instance).
|
||||||
|
|
||||||
|
## Debugging and manual git operations
|
||||||
|
|
||||||
|
The following command will show the location and status of the git repo (all git commands are available).
|
||||||
|
```
|
||||||
|
$ gopass git status
|
||||||
|
```
|
||||||
124
CONTRIBUTING/WORKFLOW.md
Normal file
124
CONTRIBUTING/WORKFLOW.md
Normal file
|
|
@ -0,0 +1,124 @@
|
||||||
|
# Development workflow
|
||||||
|
|
||||||
|
Forgejo is a soft fork, i.e. a set of commits applied to the Gitea development branch and the stable branches. On a regular basis those commits are rebased and modified if necessary to keep working. All Forgejo commits are merged into a branch from which binary releases and packages are created and distributed. The development workflow is a set of conventions Forgejo developers are expected to follow to work together.
|
||||||
|
|
||||||
|
Discussions on how the workflow should evolve happen [in the isssue tracker](https://codeberg.org/forgejo/forgejo/issues?type=all&state=open&labels=&milestone=0&assignee=0&q=%5BWORKFLOW%5D).
|
||||||
|
|
||||||
|
## Naming conventions
|
||||||
|
|
||||||
|
### Development
|
||||||
|
|
||||||
|
* Gitea: main
|
||||||
|
* Forgejo: forgejo
|
||||||
|
* Feature branches: forgejo-feature-name
|
||||||
|
|
||||||
|
### Stable
|
||||||
|
|
||||||
|
* Gitea: release/vX.Y
|
||||||
|
* Forgejo: vX.Y/forgejo
|
||||||
|
* Feature branches: vX.Y/forgejo-feature-name
|
||||||
|
|
||||||
|
### Soft fork history
|
||||||
|
|
||||||
|
Before rebasing on top of Gitea, all branches are copied to `soft-fork/YYYY-MM-DD/<branch>` for safekeeping. Older `soft-fork/*/<branch>` branches are converted into references under the same name. Similar to how pull requests store their head, they do not clutter the list of branches but can be retrieved if needed with `git fetch +refs/soft-fork/*:refs/soft-fork/*`. Tooling to automate this archival process [is available](https://codeberg.org/forgejo-contrib/soft-fork-tools/src/branch/master/README.md#archive-branches).
|
||||||
|
|
||||||
|
### Tags
|
||||||
|
|
||||||
|
Because the branches are rebased on top of Gitea, only the latest tag will be found in a given branch. For instance `v1.18.0-1` won't be found in the `v1.18/forgejo` branch after it is rebased.
|
||||||
|
|
||||||
|
## Rebasing
|
||||||
|
|
||||||
|
### *Feature branch*
|
||||||
|
|
||||||
|
The *Gitea* branches are mirrored with the Gitea development and stable branches.
|
||||||
|
|
||||||
|
On a regular basis, each *Feature branch* is rebased against the base *Gitea* branch.
|
||||||
|
|
||||||
|
### forgejo branch
|
||||||
|
|
||||||
|
The latest *Gitea* branch resets the *forgejo* branch and all *Feature branches* are merged into it.
|
||||||
|
|
||||||
|
If tests pass after pushing *forgejo* to the https://codeberg.org/forgejo-integration/forgejo repository, it can be pushed to the https://codeberg.org/forgejo/forgejo repository.
|
||||||
|
|
||||||
|
If tests do not pass, an issue is filed to the *Feature branch* that fails the test. Once the issue is resolved, another round of rebasing starts.
|
||||||
|
|
||||||
|
### Cherry picking and rebasing
|
||||||
|
|
||||||
|
Because Forgejo is a soft fork of Gitea, the commits in feature branches need to be cherry-picked on top of their base branch. They cannot be rebased using `git rebase`, because their base branch has been rebased.
|
||||||
|
|
||||||
|
Here is how the commits in the `forgejo-f3` branch can be cherry-picked on top of the latest `forgejo-development` branch:
|
||||||
|
|
||||||
|
```
|
||||||
|
$ git fetch --all
|
||||||
|
$ git remote get-url forgejo
|
||||||
|
git@codeberg.org:forgejo/forgejo.git
|
||||||
|
$ git checkout -b forgejo/forgejo-f3
|
||||||
|
$ git reset --hard forgejo/forgejo-development
|
||||||
|
$ git cherry-pick $(git rev-list --reverse forgejo/soft-fork/2022-12-10/forgejo-development..forgejo/soft-fork/2022-12-10/forgejo-f3)
|
||||||
|
$ git push --force forgejo-f3 forgejo/forgejo-f3
|
||||||
|
```
|
||||||
|
|
||||||
|
## Feature branches
|
||||||
|
|
||||||
|
All *Feature branches* are based on the {vX.Y/,}forgejo-development branch which provides development tools and documentation.
|
||||||
|
|
||||||
|
The `forgejo-development` branch is based on the {vX.Y/,}forgejo-ci branch which provides the Woodpecker CI configuration.
|
||||||
|
|
||||||
|
The purpose of each *Feature branch* is documented below:
|
||||||
|
|
||||||
|
### General purpose
|
||||||
|
|
||||||
|
* [forgejo-ci](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-ci) based on [main](https://codeberg.org/forgejo/forgejo/src/branch/main)
|
||||||
|
Woodpecker CI configuration, including the release process.
|
||||||
|
* Backports: [v1.18/forgejo-ci](https://codeberg.org/forgejo/forgejo/src/branch/v1.18/forgejo-ci)
|
||||||
|
|
||||||
|
* [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development) based on [forgejo-ci](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-ci)
|
||||||
|
Forgejo development tools and documentation.
|
||||||
|
* Backports: [v1.18/forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/v1.18/forgejo-development)
|
||||||
|
|
||||||
|
### Dependency
|
||||||
|
|
||||||
|
* [forgejo-dependency](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-dependency) based on [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development)
|
||||||
|
Each commit is prefixed with the name of dependency in uppercase, for instance **[GOTH]** or **[GITEA]**. They are standalone and implement either a bug fix or a feature that is in the process of being contributed to the dependency. It is better to contribute directly to the dependency instead of adding a commit to this branch but it is sometimes not possible, for instance when someone does not have a GitHub account. The author of the commit is responsible for rebasing and resolve conflicts. The ultimate goal of this branch is to be empty and it is expected that a continuous effort is made to reduce its content so that the technical debt it represents does not burden Forgejo long term.
|
||||||
|
* Backports: [v1.18/forgejo-dependency](https://codeberg.org/forgejo/forgejo/src/branch/v1.18/forgejo-dependency)
|
||||||
|
|
||||||
|
### [Privacy](https://codeberg.org/forgejo/forgejo/issues?labels=83271)
|
||||||
|
|
||||||
|
* [forgejo-privacy](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-privacy) based on [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development)
|
||||||
|
Customize Forgejo to have more privacy.
|
||||||
|
* Backports: [v1.18/forgejo-privacy](https://codeberg.org/forgejo/forgejo/src/branch/v1.18/forgejo-privacy)
|
||||||
|
|
||||||
|
### Branding
|
||||||
|
* [forgejo-branding](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-branding) based on [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development)
|
||||||
|
Replacing upstream branding with Forgejo branding
|
||||||
|
|
||||||
|
### [Internationalization](https://codeberg.org/forgejo/forgejo/issues?labels=82637)
|
||||||
|
* [forgejo-i18n](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-i18n) based on [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development)
|
||||||
|
Internationalization support for Forgejo with a workflow based on Weblate.
|
||||||
|
|
||||||
|
### [Accessibility](https://codeberg.org/forgejo/forgejo/issues?labels=81214)
|
||||||
|
* Backports only: [v1.18/forgejo-a11y](https://codeberg.org/forgejo/forgejo/src/branch/v1.18/forgejo-a11y) based on [v1.18/forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/v1.18/forgejo-development)
|
||||||
|
Backport future upstream a11y improvements to the current release of Forgejo
|
||||||
|
|
||||||
|
### [Federation](https://codeberg.org/forgejo/forgejo/issues?labels=79349)
|
||||||
|
|
||||||
|
* [forgejo-federation](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-federation) based on [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development)
|
||||||
|
Federation support for Forgejo
|
||||||
|
|
||||||
|
* [forgejo-f3](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-f3) based on [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development)
|
||||||
|
[F3](https://lab.forgefriends.org/friendlyforgeformat/gof3) support for Forgejo
|
||||||
|
|
||||||
|
## Pull requests and feature branches
|
||||||
|
|
||||||
|
Most people who are used to contributing will be familiar with the workflow of sending a pull request against the default branch. When that happens the reviewer should change the base branch to the appropriate *Feature branch* instead. If the pull request does not fit in any *Feature branch*, the reviewer needs to make decision to either:
|
||||||
|
|
||||||
|
* Decline the pull request because it is best contributed to Gitea
|
||||||
|
* Create a new *Feature branch*
|
||||||
|
|
||||||
|
Returning contributors can figure out which *Feature branch* to base their pull request on using the list of *Feature branches*.
|
||||||
|
|
||||||
|
## Granularity
|
||||||
|
|
||||||
|
*Feature branches* can contain a number of commits grouped together, for instance for branding the documentation, the landing page and the footer. It makes it convenient for people working on that topic to get the big picture without browsing multiple branches. Creating a new *Feature branch* for each individual commit, while possible, is likely to be difficult to work with.
|
||||||
|
|
||||||
|
Observing the granularity of the existing *Feature branches* is the best way to figure out what works and what does not. It requires adjustments from time to time depending on the number of contributors and the complexity of the Forgejo codebase that sits on top of Gitea.
|
||||||
Loading…
Add table
Reference in a new issue