mirrors/forgejo-docs
1
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2025-05-12 05:36:12 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

move docs to subfolder

Browse source
This commit is contained in:
Caesar Schinas 2023-08-15 00:20:01 +01:00
parent 385f18bd6a
commit 4125cb3cea
No known key found for this signature in database
GPG key ID: AE9108461BEA5ACF
115 changed files with 0 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

6
docs/developer/COC.md Normal file
View file

@ -0,0 +1,6 @@
---
title: Code of Conduct and moderation team
license: 'CC-BY-SA-4.0'
---
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.

32
docs/developer/DCO.md Normal file
View file

@ -0,0 +1,32 @@
---
title: Developer Certificate of Origin (DCO)
license: 'CC-BY-SA-4.0'
---
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.
```

22
docs/developer/DISCUSSIONS.md Normal file
View file

@ -0,0 +1,22 @@
---
title: Bugs, features and discussions
license: 'CC-BY-SA-4.0'
---
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/governance/src/branch/main/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.

12
docs/developer/GOVERNANCE.md Normal file
View file

@ -0,0 +1,12 @@
---
title: Governance
license: 'CC-BY-SA-4.0'
---
## 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.

196
docs/developer/RELEASE.md Normal file
View file

@ -0,0 +1,196 @@
---
title: Release management
license: 'CC-BY-SA-4.0'
---
## 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.20.0** will be Forgejo **v1.20.0-0**, **v1.20.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.20.0-rc0** will be Forgejo **v1.20.0-0-rc0**, **v1.20.0-1-rc0**
- Gitea **v1.20.0-rc1** will be Forgejo **v1.20.0-2-rc1**, **v1.20.0-3-rc1**, **v1.20.0-4-rc1**
- Gitea **v1.20.0** will be Forgejo **v1.20.0-5**, **v1.20.0-6**, **v1.20.0-7**
- etc.
Because Forgejo depends on 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 Forgejo inherits this problem.
## Release process
The TL;DR: to publish a vX.Y.Z-N release is to:
- Push the vX.Y.Z-N tag to https://codeberg.org/forgejo-integration/forgejo to trigger a workflow that will publish the release in https://codeberg.org/forgejo-experimental/forgejo
- Give it some time for people to try it out
- Push the vX.Y.Z-N tag to https://forgejo.octopuce.forgejo.org/forgejo-release/forgejo to trigger a workflow that will sign the release from https://codeberg.org/forgejo-experimental/forgejo and publish it in https://codeberg.org/forgejo-release/forgejo
### 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/). 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
### Forgejo release building and 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.
- Locally set the vX.Y.Z-N tag to the tip of the https://codeberg.org/forgejo/forgejo/vX.Y/forgejo branch
- Push the vX.Y.Z-N tag to https://codeberg.org/forgejo-integration/forgejo
Binaries are built and uploaded to https://codeberg.org/forgejo-integration/forgejo/releases
Container images are built and uploaded to https://codeberg.org/forgejo-integration/-/packages/container/forgejo/versions
If the release is successfully built, it will be copied to https://codeberg.org/forgejo/forgejo-experimental. Otherwise the logs of the workflow that tried to build the release in https://codeberg.org/forgejo-integration/forgejo/actions contains the error that needs fixing.
Fork the Forgejo [infrastructure](https://code.forgejo.org/forgejo/infrastructure) repository, [modify it](https://code.forgejo.org/earl-warren/infrastructure/commit/269eae6c3a17005ad9d825d747745da041d69756) to use the experimental release and push the branch. It will trigger [a workflow](https://code.forgejo.org/earl-warren/infrastructure/src/branch/wip-forgejo/.forgejo/workflows/forgejo.yml) to deploy the release and run high level integration tests.
Reach out to packagers and users to manually verify the release works as expected.
### Forgejo release publication
- Push the vX.Y.Z-N tag to https://forgejo.octopuce.forgejo.org/forgejo-release/forgejo
It will trigger a workflow to:
- Push the vX.Y.Z-N tag to https://codeberg.org/forgejo/forgejo
- Downoad Binaries from https://codeberg.org/forgejo-experimental, sign them and copy them to https://codeberg.org/forgejo
- Copy container images from https://codeberg.org/forgejo-experimental to https://codeberg.org/forgejo
### Forgejo runner publication
- Push the vX.Y.Z-N tag to https://code.forgejo.org/forgejo/runner
The release is built on https://code.forgejo.org/forgejo-integration/runner, which is a mirror of https://code.forgejo.org/forgejo/runner.
The release is published on
https://forgejo.octopuce.forgejo.org/forgejo/runner, which is a mirror
of https://code.forgejo.org/forgejo-integration/runner. It is behind a
VPN and its role is to copy and sign release artifacts.
- Binaries are downloaded from https://code.forgejo.org/forgejo-integration/runner, signed and copied to https://code.forgejo.org/forgejo/runner.
- Container images are copied from https://code.forgejo.org/forgejo-integration to https://code.forgejo.org/forgejo
If the publishing the release needs debug, it can be done manually:
- https://forgejo.octopuce.forgejo.org/forgejo-release/runner-debug has the same secrets as https://forgejo.octopuce.forgejo.org/forgejo-release/runner
- Make the changes, commit them, tag the commit with vX.Y.Z-N and force push the tag to https://forgejo.octopuce.forgejo.org/forgejo-release/runner-debug. Note that it does not matter that the tag is not on a commit that matches the release because this action only cares about the tag: it does not build any content itself, it copies it from one organization to another. However it matters that it matches a SHA that is found in the destination repository of the release otherwise it won't be able to set the tag (setting a tag on a non-existing sha does not work).
- Watch the action run at https://forgejo.octopuce.forgejo.org/forgejo-release/runner-debug/actions
- To skip one of the publish phases (binaries or container images), delete it and commit in the repository before pushing the tag
- Reflect the changes in a PR at https://code.forgejo.org/forgejo/runner to make sure they are not lost
It can also be done from the CLI with `forgejo-runner exec` and
providing the secrets from the command line.
### Securing the release token and cryptographic keys
For both the Forgejo runner and Forgejo itself, copying and signing the release artifacts (container images and binaries) happen on a Forgejo isntance running [behind a VPN](./infrastructure#octopuce/) to safeguard the token that has write access to the Forgejo repository as well as the cryptographic key used to sign the releases.
### Website update
- Restart the last CI build at https://codeberg.org/forgejo/website/src/branch/main/
- Verify [https://forgejo.org/download/](/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.

70
docs/developer/SECRETS.md Normal file
View file

@ -0,0 +1,70 @@
---
title: Secrets
license: 'CC-BY-SA-4.0'
---
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
```

137
docs/developer/WORKFLOW.md Normal file
View file

@ -0,0 +1,137 @@
---
title: Development workflow
license: 'CC-BY-SA-4.0'
---
Forgejo is a set of commits applied to the Gitea development branch and the stable branches. On a regular basis those commits are cherry-picked 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.
## 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
### Branches history
Before cherry-picking 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).
## Cherry-picking
### _Feature branches_
On a weekly basis all of _Forgejo_ commits are cherry-picked on top of
the latest Gitea development branch. It starts like this:
- the `forgejo-ci` branch is `reset --hard` with _Gitea_ main
- all the commits it contained are `cherry-pick -x` and conflicts resolved
- the `forgejo-ci` branch is force pushed after the CI confirms it is sane
The same is done for the `forgejo-development` branch is based on
`forgejo-ci` and the commits it contains are similarly `cherry-pick
-x`. The same is done for each _Feature branch_ until they all pass
the CI.
### Development branch
Once all _Feature branches_ are ready, the `forgejo` branch is `reset --hard`
with _Gitea_ main, all _Feature branches_ are merged into it
and it is force pushed.
### Stable branches
The stable branches are not force pushed because they would no
longer contain the tags from which releases were made. Instead, the following is done:
- The _Gitea_ commits are cherry-picked
- If there is a conflict
- revert the _Forgejo_ commit that caused the conflict
- cherry-pick the _Gitea_ commit
- cherry-pick the _Forgejo_ commit back and resolve the conflict
This ensures the conflict resolution is documented in the relevant
_Forgejo_ commit. The conflict must not be resolved in the _Gitea_
commit because there would be no convenient way to know why and how it
happened when browing the commit history.
To improve the readability of the git history, pull requests to stable
branches are rebased on top of the branch instead of being merged. It
saves one merge commit and creates a linear history.
## 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 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)
CI configuration, including the release process.
- [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, tests etc. that do not fit in a feature branch or that are used by multiple feature branches. The commits titles should be prefixed with
a string that reflects their purpose such as `[DOCS]`, `[DB]`, `[TESTS]` etc.
The database migrations of all feature branches must be in the `forgejo-development` branch. This is a requirement to ensure they do not conflict with each other
and happen in sequence.
### 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.
### [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.
### Moderation
- [forgejo-moderation](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-moderation) based on [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development)
Add moderation tooling for users and admins.
### 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)
Replace hardcoded dependencies branding with a Forgejo equivalent.
### [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 and localization support.
### [Accessibility](https://codeberg.org/forgejo/forgejo/issues?labels=81214)
- [forgejo-a11y](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-a11y) based on [forgejo-development](https://codeberg.org/forgejo/forgejo/src/branch/forgejo-development)
Accessibility improvements.
### [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.
- [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.
## 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 may ask to 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 the relevant dependency
- Create a new _Feature branch_
## 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.

17
docs/developer/code-forgejo-org.md Normal file
View file

@ -0,0 +1,17 @@
---
title: code.forgejo.org
license: 'CC-BY-SA-4.0'
---
https://code.forgejo.org is a Forgejo instance running the latest
stable version, starting with the release candidates. It is dedicated
to hosting repositories dedicated to Forgejo development, among which:
- setup-forgejo a Forgejo Action to spawn a Forgejo instance and a runner for testing purposes https://code.forgejo.org/actions/setup-forgejo
- Forgejo Runner https://code.forgejo.org/forgejo/runner
- [ACT](https://github.com/nektos/act) soft fork https://code.forgejo.org/forgejo/act
To make these repositories easier to find, the following push mirrors are in place:
- https://code.forgejo.org/forgejo/runner => https://codeberg.org/forgejo/runner
- https://code.forgejo.org/forgejo/act => https://codeberg.org/forgejo/act

117
docs/developer/from-source.md Normal file
View file

@ -0,0 +1,117 @@
---
title: 'Compiling from source'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/installation/from-source.en-us.md'
---
## Installation from source
You should [install go](https://golang.org/doc/install) and set up your go
environment correctly. In particular, it is recommended to set the `$GOPATH`
environment variable and to add the go bin directory or directories
`${GOPATH//://bin:}/bin` to the `$PATH`. See the Go wiki entry for
[GOPATH](https://github.com/golang/go/wiki/GOPATH).
Next, [install Node.js with npm](https://nodejs.org/en/download/) which is
required to build the JavaScript and CSS files. The minimum supported Node.js
version is 16 and the latest LTS version is recommended.
**Note**: When executing make tasks that require external tools, like
`make misspell-check`, Forgejo will automatically download and build these as
necessary. To be able to use these, you must have the `"$GOPATH/bin"` directory
on the executable path. If you don't add the go bin directory to the
executable path, you will have to manage this yourself.
**Note 2**: Go version 1.20 or higher is required. However, it is recommended to
obtain the same version as our continuous integration, see the advice given in
[Hacking on Forgejo]({{< relref "doc/development/hacking-on-forgejo.en-us.md" >}})
### Download
First, we must retrieve the source code. Since, the advent of go modules, the
simplest way of doing this is to use Git directly as we no longer have to have
Forgejo built from within the GOPATH.
```bash
git clone https://codeberg.org/forgejo/forgejo
```
Decide which version of Forgejo to build and install. Currently, there are
multiple options to choose from. The `forgejo` branch represents the current
development version.
To work with tagged releases, the following commands can be used:
```bash
git branch -a
git checkout v1.20.0-5
```
To build Forgejo from source at a specific tagged release (like v1.20.0-5), list the
available tags and check out the specific tag.
List available tags with the following.
```bash
git tag -l
git checkout v1.20.0-5
```
### Build
To build from source, the following programs must be present on the system:
- `go` v1.20 or higher, see [here](https://golang.org/dl/)
- `node` 16 or higher with `npm`, see [here](https://nodejs.org/en/download/)
- `make`
Depending on requirements, the following build tags can be included.
- `bindata`: Build a single monolithic binary, with all assets included. Required for production build.
- `sqlite sqlite_unlock_notify`: Enable support for a
[SQLite3](https://sqlite.org/) database. Suggested only for small
installations.
- `pam`: Enable support for PAM (Linux Pluggable Authentication Modules). Can
be used to authenticate local users or extend authentication to methods
available to PAM.
Using the `bindata` build tag is required for production
deployments. You could exclude `bindata` when you are
developing/testing Forgejo or able to separate the assets correctly.
To include all assets, use the `bindata` tag:
```bash
TAGS="bindata" make build
```
In the default release build of the continuous integration system, the build
tags are: `TAGS="bindata sqlite sqlite_unlock_notify"`. The simplest
recommended way to build from source is therefore:
```bash
TAGS="bindata sqlite sqlite_unlock_notify" make build
```
The `build` target is split into two sub-targets:
- `make backend` which requires [Go v1.20](https://golang.org/dl/) or greater.
- `make frontend` which requires [Node.js 16](https://nodejs.org/en/download/) or greater.
If pre-built frontend files are present it is possible to only build the backend:
```bash
TAGS="bindata" make backend
```
Webpack source maps are by default enabled in development builds and disabled in production builds. They can be enabled by setting the `ENABLE_SOURCEMAP=true` environment variable.
### Test
After following the steps above, a `forgejo` binary will be available in the working directory.
It can be tested from this directory or moved to a directory with test data. When Forgejo is
launched manually from command line, it can be killed by pressing `Ctrl + C`.
```bash
./forgejo web
```

22
docs/developer/index.md Normal file
View file

@ -0,0 +1,22 @@
---
title: 'Forgejo developer guide'
---
This area will be targeted to people who want to hack Forgejo and adjust it to
their needs.
- For everyone involved
- [Code of Conduct](./coc/)
- [Bugs, features, security and others discussions](./discussions/)
- [Governance](./governance/)
- [Sustainability and funding](https://codeberg.org/forgejo/sustainability/src/branch/master/README)
- For contributors
- [Compiling from source](./from-source/)
- [Developer Certificate of Origin (DCO)](./dco/)
- [Development workflow](./workflow/)
- [code.forgejo.org](./code-forgejo-org/)
- [Forgejo runner implementation notes](https://code.forgejo.org/forgejo/runner/#hacking)
- For maintainers
- [Hardware infrastructure](./infrastructure/)
- [Release management](./release/)
- [Secrets](./secrets/)

107
docs/developer/infrastructure.md Normal file
View file

@ -0,0 +1,107 @@
---
title: Hardware infrastructure
license: 'CC-BY-SA-4.0'
---
## Codeberg
Codeberg provides a LXC container with 48GB RAM, 24 threads and SSD drive to be used for the CI. A Forgejo Runner is installed in `/opt/runner` and registered with a token obtained from https://codeberg.org/forgejo. It does not allow running privileged containers or LXC containers for security reasons. The runner is intended to be used for pull requests, for instance in https://codeberg.org/forgejo/forgejo.
## Octopuce
[Octopuce provides hardware](https://codeberg.org/forgejo/sustainability) managed by [the devops team](https://codeberg.org/forgejo/governance/src/branch/main/TEAMS.md#devops). It can be accessed via a VPN which provides a DNS for the `octopuce.forgejo.org` internal domain.
The VPN is deployed and upgraded using the following [Enough command line](https://enough-community.readthedocs.io):
```shell
$ mkdir -p ~/.enough
$ git clone https://forgejo.octopuce.forgejo.org/forgejo/enough-octopuce ~/.enough/octopuce.forgejo.org
$ enough --domain octopuce.forgejo.org service create openvpn
```
## Hetzner
https://hetzner01.forgejo.org runs on an [EX101](https://www.hetzner.com/dedicated-rootserver/ex101) Hetzner hardware.
## OVH
https://code.forgejo.org runs on an OVH virtual machine using the same
OVH account used for the forgejo.org domain name and mails.
It is deployed and upgraded using the following [Enough command line](https://enough-community.readthedocs.io):
```shell
$ mkdir -p ~/.enough
$ git clone https://forgejo.octopuce.forgejo.org/forgejo/enough-code ~/.enough/code.forgejo.org
$ enough --domain code.forgejo.org service create --host bind-host forgejo
```
Upgrading only Forgejo:
```shell
$ enough --domain code.forgejo.org playbook -- --limit bind-host,localhost --private-key ~/.enough/code.forgejo.org/infrastructure_key venv/share/enough/playbooks/forgejo/forgejo-playbook.yml
```
Login in the machine hosting the Forgejo instance for debugging purposes:
```shell
enough --domain code.forgejo.org ssh bind-host
```
## Installing Forgejo runners
### Preparing the LXC hypervisor
```shell
git clone https://code.forgejo.org/forgejo/lxc-helpers/
lxc-helpers.sh lxc_prepare_environment
sudo lxc-helpers.sh lxc_install_lxc_inside 10.120.13
```
### Creating an LXC container
```shell
lxc-helpers.sh lxc_container_create forgejo-runners
lxc-helpers.sh lxc_container_start forgejo-runners
lxc-helpers.sh lxc_container_user_install forgejo-runners $(id -u) $USER
lxc-helpers.sh lxc_container_run forgejo-runners -- sudo --user debian bash
sudo apt-get update
sudo apt-get install -y wget docker.io emacs-nox
sudo usermod -aG docker $USER # exit & enter again for the group to be active
lxc-helpers.sh lxc_prepare_environment
sudo wget -O /usr/local/bin/forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v2.0.4/forgejo-runner-amd64
sudo chmod +x /usr/local/bin/forgejo-runner
echo 'export TERM=vt100' >> .bashrc
```
### Creating a runner
Multiple runners can co-exist on the same machine. To keep things
organized they are located in a directtory that is the same as the url
from which the token is obtained. For instance
DIR=codeberg.org/forgejo-integration means that the token was obtained from the
https://codeberg.org/forgejo-integration organization.
If a runner only provides unprivileged docker containers, the labels
should be
`LABELS=docker:docker://node:16-bullseye,ubuntu-latest:docker://node:16-bullseye`.
If a runner provides LXC containers and unprivileged docker
containers, the labels should be
`LABELS=docker:docker://node:16-bullseye,self-hosted`.
```shell
mkdir -p $DIR ; cd $DIR
forgejo-runner generate-config > config.yml
## edit config.yml
## Obtain a $TOKEN from https://$DIR
forgejo-runner register --no-interactive --token $TOKEN --name runner --instance https://codeberg.org --labels $LABELS
forgejo-runner --config config.yml daemon |& cat -v > runner.log &
```
#### codeberg.org config.yml
- `fetch_timeout: 30s` # because it can be slow at times
- `fetch_interval: 60s` # because there is throttling and 429 replies will mess up the runner
- cache `enabled: false` # because codeberg.org is still v1.19