foster/forgejo-docs
0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-11-24 18:09:26 -05:00
Code Issues Activity

docs: run format

Browse source
This commit is contained in:
Earl Warren 2023-05-02 20:26:08 +02:00 committed by Caesar Schinas
parent e06b403a6f
commit c298c386db
No known key found for this signature in database
GPG key ID: AE9108461BEA5ACF
6 changed files with 109 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
developer/COC.md
View file

@ -31,4 +31,4 @@ 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
- https://codeberg.org/circlebuilder

1
developer/DISCUSSIONS.md
View file

@ -7,6 +7,7 @@ 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).

110
developer/RELEASE.md
View file

@ -8,14 +8,14 @@ license: 'CC-BY-SA-4.0'
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
- 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.
- 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.
@ -27,61 +27,61 @@ When publishing the vX.Y.Z-N release, the following steps must be followed:
### Semantic version
* Update the FORGEJO_VERSION variable in the Makefile
- 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
- 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
- `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/
- 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
- 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
- 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
- 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`
- Update the `release.forgejo.org` TXT record that starts with `forgejo_versions=` to be `forgejo_versions=vX.Y.Z-N`
### Standard toot
@ -97,37 +97,37 @@ A GPG master key with no expiration date is created and shared with members of t
### 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
- 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
- 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
- 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`
- `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

11
developer/SECRETS.md
View file

@ -10,6 +10,7 @@ All Forgejo credentials are shared among the [secret keepers](https://codeberg.o
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
@ -17,13 +18,17 @@ $ gpg --import public_key.asc
# 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
```
@ -31,30 +36,36 @@ $ 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
```

70
developer/WORKFLOW.md
View file

@ -12,15 +12,15 @@ Discussions on how the workflow should evolve happen [in the isssue tracker](htt
### Development
* Gitea: main
* Forgejo: forgejo
* Feature branches: forgejo-feature-name
- 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
- Gitea: release/vX.Y
- Forgejo: vX.Y/forgejo
- Feature branches: vX.Y/forgejo-feature-name
### Soft fork history
@ -32,19 +32,19 @@ Because the branches are rebased on top of Gitea, only the latest tag will be fo
## Rebasing
### *Feature branch*
### _Feature branch_
The *Gitea* branches are mirrored with the Gitea development and stable branches.
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.
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.
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 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.
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
@ -64,65 +64,69 @@ $ 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.
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:
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)
- [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)
- 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)
- 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)
- [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)
- 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)
- [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)
- 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)
- [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)
- [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)
- 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)
- [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)
- [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:
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*
- 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*.
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.
_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.
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.