[DOCS] CONTRIBUTING

Refs: https://codeberg.org/forgejo/forgejo/issues/8
Reviewed-on: https://codeberg.org/forgejo/forgejo/pulls/153
This commit is contained in:
Loïc Dachary 2022-12-17 14:06:28 +01:00
parent 6a06404f49
commit 80bd07dba3
Signed by untrusted user: dachary
GPG key ID: 992D23B392F9E4F2
8 changed files with 390 additions and 0 deletions

23
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,23 @@
# 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
- [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)

31
CONTRIBUTING/COC.md Normal file
View file

@ -0,0 +1,31 @@
# Code of Conduct, Well Being and Moderation teams
Forgejo strives to be an inclusive project where everyone can participate in a safe environment. The **Well Being** team is doing its best to defuse tensions before they escalate and is available to answer all requests sent its way. When diplomacy fails, the **Moderation** team will be forced to act to put a stop to actions that are contrary to the [Code of Conduct](https://codeberg.org/forgejo/code-of-conduct).
## Well Being and Moderation teams
Temporary Well Being and Moderation teams [were appointed 10 November 2022](https://codeberg.org/forgejo/meta/issues/13).
The moderation team will rely on this [Code of Conduct](https://codeberg.org/forgejo/code-of-conduct) when diplomacy fails.
### Well Being
Their goal is to defuse tensions.
It has no power whatsover. The members are approved by the organization and trusted to:
- Read all communications to detect tensions between people before they escalate.
- Do their best to defuse tensions.
* https://codeberg.org/Gusted
* https://codeberg.org/dachary
### Moderation
Their goal is to enforce the [Code of Conduct](https://codeberg.org/forgejo/code-of-conduct) when diplomacy fails.
It has the power to exclude people from a space.
Their decisions must be logical, fact based and transparent to the Forgejo community who trust them with this responsibility.
* https://codeberg.org/circlebuilder

29
CONTRIBUTING/DCO.md Normal file
View 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
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.
```

View 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 the [meta issue tracker](https://codeberg.org/forgejo/meta/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.

View file

@ -0,0 +1,19 @@
# 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
See our [decision-making system](https://codeberg.org/forgejo/meta/src/branch/readme/DECISION-MAKING.md) (contains team agreements and guidelines).
Forgejo was bootstraped in November 2022 and is in the process of [defining its governance](https://codeberg.org/forgejo/meta/issues/19). The [first meeting happened November 24th](https://codeberg.org/forgejo/meta/issues/19#issuecomment-694460) and everyone is welcome to participate.
## Interim Forgejo Governance
While the governance is being defined, there was a need to establish an interim Forgejo governance for safeguarding credentials, enforcing the Code of Conduct and ensuring security vulnerabilities are handled responsibly for the Forgejo releases.
All people with a role in the interim Forgejo governance pledge to resign as soon as the Forgejo governance is in place.
The people and teams that are part of the interim governance are [listed publicly](https://codeberg.org/forgejo/meta/src/branch/readme/TEAMS.md).

100
CONTRIBUTING/RELEASE.md Normal file
View file

@ -0,0 +1,100 @@
# 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
### Integration
* Reset the vX.Y/forgejo branch to the Gitea tag vX.Y.Z
* Merge all feature branches into the vX.Y/forgejo branch
### Testing
When Forgejo is released, artefacts (packages, binaries, etc.) are first published by the CI/CD pipelines in the https://codeberg.org/forgejo-integration organization, to be downloaded and verified to work. When modifying the CI/CD pipelines, there is a chance that these verification steps fail and that the published artefacts override previous ones or worse. During this debugging phase, a fork of Forgejo must be used.
* Push the vX.Y.Z-N tag to a Forgejo fork (e.g. https://codeberg.org/someuser/forgejo)
* Verify the release is published in https://codeberg.org/forgejo-integration
* Verify the release is published in https://codeberg.org/someuser
### Publication
* Push the vX.Y.Z-N tag to https://codeberg.org/forgejo/forgejo
* [Binaries](https://codeberg.org/forgejo/forgejo/releases) are built, signed and uploaded by the CI.
* [Container images](https://codeberg.org/forgejo/-/packages/container/forgejo/versions) are built and uploaded by the CI.
### 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
* Manually try the instructions to work
## 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>`
## Integration 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 `release-team` user as well as all Forgejo contributors working on the CI/CD pipeline should be owners of the `forgejo-integration` organization. Assuming `someuser` is such a user, they can use this organization to verify a modified CI/CD pipeline behaves as expected before actually trying to publish anything for real at https://codeberg.org/forgejo.
* Modify files in the `.woodpecker` directory
* Set a tag (e.g. v10.0.0)
* Push the tag to `https://codeberg.org/someouser/forgejo`
* After the CI/CD pipeline completes the artefacts (release, package, etc.) must be available and identical at https://codeberg.org/someouser/forgejo and https://codeberg.org/forgejo-integration/forgejo

56
CONTRIBUTING/SECRETS.md Normal file
View 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
```

114
CONTRIBUTING/WORKFLOW.md Normal file
View file

@ -0,0 +1,114 @@
# 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.
## 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
```
## Releasing
When a tag is set to a *Stable* *Forgejo* branch, the CI pipeline creates and uploads binaries and packages.
## Feature branches
All *Feature branches* are based on the {vX.Y/,}forgejo-development branch which provides and other 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)
### [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.
### [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.