dallasgroot/Documentation
1
0
Fork 0
mirror of https://codeberg.org/Codeberg/Documentation.git synced 2026-06-16 05:13:54 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

Reduce line length limit and format content (#623)

Browse source 
# Changelog

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

## Changed

- Update line length limit from 500 characters to 120 characters.

## Fixed

- Most instances of these lint issues:
  1. Lines longer than 120 characters ([MD013](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md013.md)).
  2. Trailing whitespaces ([MD009](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md)).
  3. Ordered list item prefix ([MD029](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md029.md)).
  4. Bare links ([MD034](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md034.md)).

Co-authored-by: Patrick Schratz <pat-s@noreply.codeberg.org>
Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/623
Reviewed-by: Patrick Schratz <pat-s@noreply.codeberg.org>
Co-authored-by: Javier Pérez <walpo@noreply.codeberg.org>
Co-committed-by: Javier Pérez <walpo@noreply.codeberg.org>
This commit is contained in:
Javier Pérez 2025-06-14 11:38:21 +02:00 committed by Patrick Schratz
parent 100beaacea
commit c6ac9a9f94
62 changed files with 1331 additions and 573 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.markdownlint.yaml
View file

@ -45,7 +45,7 @@ MD012:
# MD013/line-length - Line length
MD013:
# Number of characters
line_length: 500
line_length: 120
# Number of characters for headings
heading_line_length: 100
# Number of characters for code blocks

3
LICENSE.md
View file

@ -16,4 +16,5 @@ licensed under [multiple licenses](https://fontawesome.com/license/free).
Codeberg and the Codeberg Logo are trademarks of Codeberg e.V.
"Knut the Polar Bear" has been derived from [https://openclipart.org/detail/193243/polar-bear-remix](https://openclipart.org/detail/193243/polar-bear-remix), under CC0 1.0
"Knut the Polar Bear" has been derived from [https://openclipart.org/detail/193243/polar-bear-remix](https://openclipart.org/detail/193243/polar-bear-remix),
under CC0 1.0

13
README.md
View file

@ -3,7 +3,9 @@
This repository contains the [documentation for Codeberg](https://docs.codeberg.org/), with some code to build it into
a static website.
Please have a look into it and consider to help writing the Documentation. This is still very much work-in-progress, the more useful material we collect, the better we can later present it! All contributions are very welcome!
Please have a look into it and consider to help writing the Documentation.
This is still very much work-in-progress, the more useful material we collect, the better we can later present it!
All contributions are very welcome!
For an introduction on contributing to Codeberg Documentation, please have a look
at [the section on improving the documentation](https://docs.codeberg.org/improving-documentation/).
@ -93,15 +95,18 @@ with `package-lock.json` to try to ensure reproducible builds.
It also uses [PageFind](https://pagefind.app/), a static search library.
Deployment previews are generated for every PR using [Surge.sh](https://surge.sh/) through the corresponding [Woodpecker plugin](https://woodpecker-ci.org/plugins/surge-preview-plugin).
Deployment previews are generated for every PR using [Surge.sh](https://surge.sh/)
through the corresponding [Woodpecker plugin](https://woodpecker-ci.org/plugins/surge-preview-plugin).
A spellchecker is used to check for spelling errors in the documentation.
To add exceptions to the spellchecker, add them to the `.cspell.json` file.
This project is deployed to Codeberg via [a cron job](https://codeberg.org/Codeberg-Infrastructure/scripted-configuration/src/branch/main/hosts/static/home/build/build_docs.sh) executed on the Codeberg infrastructure.
This project is deployed to Codeberg via [a cron job](https://codeberg.org/Codeberg-Infrastructure/scripted-configuration/src/branch/main/hosts/static/home/build/build_docs.sh)
executed on the Codeberg infrastructure.
## License and Contributors
This website (excluding bundled fonts) is licensed under CC BY-SA 4.0. See the [LICENSE](LICENSE.md) file for details.
Please refer to the [commit log](https://codeberg.org/Codeberg/Documentation/commits/branch/main) for an exhaustive list of contributors to Codeberg Documentation.
Please refer to the [commit log](https://codeberg.org/Codeberg/Documentation/commits/branch/main)
for an exhaustive list of contributors to Codeberg Documentation.

16
content/advanced/access-token.md
View file

@ -5,11 +5,14 @@ eleventyNavigation:
parent: AdvancedUsage
---
Access Tokens are special tokens that are used to authenticate to Codeberg through the [API](https://codeberg.org/api/swagger). They can be used to give applications access to your Codeberg account without sharing your password.
Access Tokens are special tokens that are used to authenticate to Codeberg through the [API](https://codeberg.org/api/swagger).
They can be used to give applications access to your Codeberg account without sharing your password.
{% admonition "info" %}
This guide explains how to generate an access token from the website. However, you can also generate access tokens from the API. Read more at [Forgejo's documentation](https://forgejo.org/docs/latest/user/api-usage/#generating-and-listing-api-tokens).
This guide explains how to generate an access token from the website.
However, you can also generate access tokens from the API.
Read more at [Forgejo's documentation](https://forgejo.org/docs/latest/user/api-usage/#generating-and-listing-api-tokens).
{% endadmonition %}
@ -19,7 +22,8 @@ Access tokens grant full access to your account. You must handle them securely.
<img src="/images/advanced/access-token/generate-token.png" alt="">
1. In a web browser, go to Codeberg and click on the `Profiles and Settings` button on the top right. The button will be your profile picture.
1. In a web browser, go to Codeberg and click on the `Profiles and Settings` button on the top right.
The button will be your profile picture.
2. Click on [`Settings`](https://codeberg.org/user/settings) in the dropdown.
3. Navigate to the [`Applications`](https://codeberg.org/user/settings/applications) settings tab.
4. Under `Manage Access Tokens | Generate New Token`, enter a name to identify your token in the `Token Name` field.
@ -37,6 +41,8 @@ Be sure to generate new access tokens for each app you use, and delete them once
## Deleting an Access Token
Once you are done using an access token, you should delete it. Deleting an access token revokes access to your account for apps using the token.
Once you are done using an access token, you should delete it.
Deleting an access token revokes access to your account for apps using the token.
To delete an access token, click the red `Delete` button next to the access token you want to delete, then click `Yes` in the popup. Your access token is now deleted.
To delete an access token, click the red `Delete` button next to the access token you want to delete,
then click `Yes` in the popup. Your access token is now deleted.

35
content/advanced/migrating-repos.md
View file

@ -8,15 +8,20 @@ eleventyNavigation:
Using a distributed version control software system (like Git) allows you to keep control of the data inside the repository.
If you want to download a local copy of your files, you can `git clone` your repo, or download the repo from the web interface.
This works well for moving files, but when you want to migrate metadata like issues, releases and a wiki, you can use the migration tool.
This works well for moving files, but when you want to migrate metadata like issues,
releases and a wiki, you can use the migration tool.
<img src="/images/advanced/migrating-repos/new-migration.png" alt="Dropdown showing the new migration item">
On Codeberg, you can click on the plus symbol on the top right, and then select [**New Migration**](https://codeberg.org/repo/migrate) on the dropdown to access the migration tool.
On Codeberg, you can click on the plus symbol on the top right, and then select [**New Migration**](https://codeberg.org/repo/migrate)
on the dropdown to access the migration tool.
## Selecting your host
Once you're at the [**New Migration**](https://codeberg.org/repo/migrate) page, you can select the Git host you are migrating from. For the following services, the migration tool can not only migrate your repository data, but also metadata like issues, labels, wiki, releases, milestones, etc.
Once you're at the [**New Migration**](https://codeberg.org/repo/migrate) page,
you can select the Git host you are migrating from.
For the following services, the migration tool can not only migrate your repository data, but also metadata like issues,
labels, wiki, releases, milestones, etc.
- [GitHub](#migrating-from-services)
- [GitLab](#migrating-from-services)
@ -28,7 +33,8 @@ Once you're at the [**New Migration**](https://codeberg.org/repo/migrate) page,
If you cannot find your service, you can select the [Git option](#migrating-from-git). This will not migrate mentioned metadata.
Here we document instructions for migrating specific to each service. Once you've followed through, move on to [Starting Migration](#starting-migration).
Here we document instructions for migrating specific to each service.
Once you've followed through, move on to [Starting Migration](#starting-migration).
### Migrating from Git
@ -37,18 +43,23 @@ Here we document instructions for migrating specific to each service. Once you'v
Here's an explanation of some fields on the [Git migration page](https://codeberg.org/repo/migrate?service_type=1):
- **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git`.
- **Username and Password**: Optionally, if authentication is required to access the repo, you can enter a username and password here.
- **Username and Password**: Optionally, if authentication is required to access the repo,
you can enter a username and password here.
### Migrating from Services
To migrate a repo with its metadata from a different service, you will first need to [create an access token](/advanced/access-token/) on the service with your repository. _Please check your services documentation, on how to get the access token._ Examples can be found for [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) and [GitHub](https://github.com/settings/tokens). Don't forget to delete the access token once you are finished.
To migrate a repo with its metadata from a different service, you will first need to [create an access token](/advanced/access-token/)
on the service with your repository. _Please check your services documentation, on how to get the access token._
Examples can be found for [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) and [GitHub](https://github.com/settings/tokens).
Don't forget to delete the access token once you are finished.
<img src="/images/advanced/migrating-repos/gitea-migration.png" alt="">
Here's an explanation of some fields on the [Gitea migration page](https://codeberg.org/repo/migrate?service_type=3):
- **Migrate / Clone From URL**: This is the URL to your repository. For example: `https://code.forgejo.org/forgejo/end-to-end`.
- **Access Token**: You will paste the access token generated here. An access token is required to migrate metadata or non-public repositories.
- **Access Token**: You will paste the access token generated here. An access token is required to migrate metadata or
non-public repositories.
- **Migration Items**: Here you can select the metadata you want migrated.
- **Owner**: The new owner of the migrated repository.
- **Repository Name**: The name of the migrated repository.
@ -70,10 +81,14 @@ When the repo code appears, migration is complete!
## Inaccessible repo after failed migration
Sometimes a migration might fail for no obvious reasons like timeouts or invalid data in the source repo, leaving you with an inaccessible repo on Codeberg.
When you try to navigate to your repo on Codeberg, e.g. `https://codeberg.org/knut/example/`, you are welcomed with a `500 Internal Server Error`.
Sometimes a migration might fail for no obvious reasons like timeouts or invalid data in the source repo,
leaving you with an inaccessible repo on Codeberg.
When you try to navigate to your repo on Codeberg, e.g. `https://codeberg.org/knut/example/`,
you are welcomed with a `500 Internal Server Error`.
In this case it might be worthwhile to retry the migration.
First you need to remove the inaccessible repo. To do so, go to the settings page of your repo by appending `/settings` to the URI, e.g. `https://codeberg.org/knut/example/settings`. You can delete the repo from here and start over with a new migration.
First you need to remove the inaccessible repo. To do so, go to the settings page of your repo by appending `/settings`
to the URI, e.g. `https://codeberg.org/knut/example/settings`.
You can delete the repo from here and start over with a new migration.
If this doesn't work out, feel free to open an issue in the [Community Issue Tracker](https://codeberg.org/Codeberg/Community/issues).

36
content/advanced/using-webhooks.md
View file

@ -5,7 +5,9 @@ eleventyNavigation:
parent: AdvancedUsage
---
Webhooks can help you to automate working with your repository. For example it can trigger an defined action if someone pushes to your repository or opens a new issue by using a target web URL.
Webhooks can help you to automate working with your repository.
For example it can trigger an defined action if someone pushes to your repository or opens a new issue by using
a target web URL.
Detailed documentation on how to use webhooks can be found in the [forgejo Documentation](https://forgejo.org/docs/latest/user/webhooks/).
@ -24,11 +26,14 @@ Currently, Codeberg offers implementation templates for the following services:
- WeCom
- Packagist
Every service that offers webhook functionality can be added using the **Forgejo** template using the **webhook URL** provided by the service.
Every service that offers webhook functionality can be added using the **Forgejo** template using the **webhook URL**
provided by the service.
## Using Read the Docs
To better illustrate how webhooks can be used, we prepared a tutorial for you that works with \*[Read the Docs](https://readthedocs.io). In this example, we will show you how to build your documentation every time that a new commit is pushed to your Codeberg repository.
To better illustrate how webhooks can be used, we prepared a tutorial for you that works with \*[Read the Docs](https://readthedocs.io).
In this example, we will show you how to build your documentation every time that a new commit is pushed to
your Codeberg repository.
<img src="/images/advanced/using-webhooks/using-webhooks-readthedocs-2.jpg" alt="Open the admin settings on ReadTheDocs">
@ -36,12 +41,13 @@ To better illustrate how webhooks can be used, we prepared a tutorial for you th
2. Click on the **Admin** button.
3. In the left side menu, click on **Integrations**.
<img src="/images/advanced/using-webhooks/using-webhooks-readthedocs-3.jpg" alt="Open the admin settings on ReadTheDocs">
<img src="/images/advanced/using-webhooks/using-webhooks-readthedocs-3.jpg" alt="Open the admin settings on ReadTheDocs">
4. Click on the button **Add Integration**.
5. Select **GitHub incoming webhook**. (GitHub, GitLab or BitBucket incoming webhooks, all work equally well and generate the needed webhook URL)
5. Select **GitHub incoming webhook**. (GitHub, GitLab or BitBucket incoming webhooks,
all work equally well and generate the needed webhook URL)
<img src="/images/advanced/using-webhooks/using-webhooks-readthedocs-4.jpg" alt="Open the admin settings on ReadTheDocs">
<img src="/images/advanced/using-webhooks/using-webhooks-readthedocs-4.jpg" alt="Open the admin settings on ReadTheDocs">
6. A **webhook address** will be displayed to you. Write it down and keep it safe!
@ -50,23 +56,29 @@ Now go to your Codeberg repository.
1. Go to your repository and click on **Settings**.
2. In the top menu, click on **Webhooks**.
<img src="/images/advanced/using-webhooks/using-webhooks-codeberg-1.jpg" alt="Open the admin settings on ReadTheDocs">
<img src="/images/advanced/using-webhooks/using-webhooks-codeberg-1.jpg" alt="Open the admin settings on ReadTheDocs">
3. Click on **Add Webhook** and choose **Forgejo**.
4. Paste the **webhook address** provided by _Read the Docs_ into the **Target URL** field.
5. You can select when the webhook should be triggered using the **Trigger On** setting. For illustrative purposes, we will select **Push Events**; this will trigger the webhook every time that someone pushes to your repository.
5. You can select when the webhook should be triggered using the **Trigger On** setting.
For illustrative purposes, we will select **Push Events**; this will trigger the webhook every time that someone
pushes to your repository.
<img src="/images/advanced/using-webhooks/using-webhooks-codeberg.jpg" alt="Open the admin settings on ReadTheDocs">
In this example, we do not need to use any other fields to make the webhook work. For your personal reference, here are some explanations as to what these other fields do:
In this example, we do not need to use any other fields to make the webhook work.
For your personal reference, here are some explanations as to what these other fields do:
- **HTTP Method**: Should be "POST" by default, so that the data is sent within the HTTP header
- **POST Content Type**: specifies how the data should be sent in the header. "application/json" and "application/x-www-form-urlencoded" both work with _Read the Docs_
- **POST Content Type**: specifies how the data should be sent in the header. "application/json"
and "application/x-www-form-urlencoded" both work with _Read the Docs_
- **Secret**: For authentication reasons, you can send a secret. For ReadTheDocs leave it empty.
- **Branch filter**: You can define, that the webhook is only triggered on certain branches in your repository
- **Authorization Header**: Some services need an authorization to call the webhook
Once you're done, you can click on **Add Webhook** to add the webhook to your repository.
Now, whenever something is pushed to your repository, the webhook will trigger and your _Read the Docs_ documentation will be rebuilt.
Now, whenever something is pushed to your repository, the webhook will trigger and your _Read the Docs_ documentation
will be rebuilt.
You can confirm that everything is working as it should by selecting the webhook that you just created and clicking on the button **Test Delivery**, which will manually trigger your webhook.
You can confirm that everything is working as it should by selecting the webhook that you just created and clicking on
the button **Test Delivery**, which will manually trigger your webhook.

27
content/ci/actions.md
View file

@ -5,28 +5,34 @@ eleventyNavigation:
parent: CI
---
Actions is a continuous integration and continuous delivery (CI/CD) feature that allows you to automate your build, test and deployment pipelines in Forgejo, the software Codeberg uses. For more information, please read [Forgejo's Documentation](https://forgejo.org/docs/latest/user/actions/).
Actions is a continuous integration and continuous delivery (CI/CD) feature that allows you to automate your build,
test and deployment pipelines in Forgejo, the software Codeberg uses.
For more information, please read [Forgejo's Documentation](https://forgejo.org/docs/latest/user/actions/).
Due to outstanding security issues and bus factor (we need more maintainers for our CI service),
we are currently providing hosted Actions in limited fashion: see https://codeberg.org/actions/meta.
we are currently providing hosted Actions in limited fashion: see <https://codeberg.org/actions/meta>.
If you need Codeberg to host your CI, please use Woodpecker CI instead.
But you can already connect your own Runner to Codeberg.
CI jobs will run on your machine, and the result will be displayed in Codeberg.
This guide will walk you through setting up your own [Forgejo Actions](https://forgejo.org/2023-02-27-forgejo-actions/) Runner to use for CI jobs.
This guide will walk you through setting up your own [Forgejo Actions](https://forgejo.org/2023-02-27-forgejo-actions/)
Runner to use for CI jobs.
## Obtaining a registration token
{% admonition "info" "Make sure to enable actions" %}
Repository Actions are disabled by default and will require you to enable them in the "Units" > "Overview" section of your repository's settings page.
Repository Actions are disabled by default and will require you to enable them in the "Units" > "Overview" section
of your repository's settings page.
{% endadmonition %}
Before deploying the Runner, you need to obtain a registration token from Codeberg. Registration tokens are used by the Runner and Codeberg to share secrets and configurations.
Before deploying the Runner, you need to obtain a registration token from Codeberg. Registration tokens are used
by the Runner and Codeberg to share secrets and configurations.
You can add Runners to your account, organization, or repository. Choosing where you obtain the registration token will determine where your Runner will accept workflows from.
You can add Runners to your account, organization, or repository. Choosing where you obtain the registration token will
determine where your Runner will accept workflows from.
1. Go to the account/organization/repository settings page.
@ -74,7 +80,8 @@ Before you deploy the Runner, you need to generate its configuration files and m
You can generate them to your current directory by either running the binary on host or in a Docker container.
Make sure to replace `{TOKEN}` with the registration token you copied, and `{NAME}` with any identifier to monitor it on Codeberg.
Make sure to replace `{TOKEN}` with the registration token you copied, and `{NAME}` with any identifier to monitor it
on Codeberg.
### Binary
@ -126,7 +133,8 @@ $ DOCKER_HOST=unix://${XDG_RUNTIME_DIR}/podman/podman.sock ./forgejo-runner daem
{% endadmonition %}
Since this method requires access to the Docker socket, you will need to get the GID of the Docker group (usually `docker`) in your host machine by running:
Since this method requires access to the Docker socket, you will need to get the GID of the Docker group
(usually `docker`) in your host machine by running:
```bash
$ id | grep -Po '\d+\(docker\)'
@ -183,7 +191,8 @@ Docker in Docker (dind) requires elevated privileges on Kubernetes.
The current way to achieve this is to set the pod `SecurityContext` to `privileged`.
Keep in mind that this is a potential security issue that can allow a malicious application to break out of the container context.
Keep in mind that this is a potential security issue that can allow a malicious application to break out of the
container context.
{% endadmonition %}

30
content/ci/index.md
View file

@ -6,10 +6,13 @@ eleventyNavigation:
order: 65
---
Every piece of code should be tested regularly. Ideally developers already implement unit-tests to test the functionality of code sections.
Some projects even implement a suite of integration tests, testing whether the code in different parts of the software works as a whole and (still) provides the functionality the software promises to deliver.
Every piece of code should be tested regularly. Ideally developers already implement unit-tests to test the
functionality of code sections.
Some projects even implement a suite of integration tests, testing whether the code in different parts of the software
works as a whole and (still) provides the functionality the software promises to deliver.
Running these tests regularly (or continuously) is the job of a Continuous Integration (CI) solution.
The results of the tests are displayed to the project members and maintainers, enabling them to identify problems and react if errors occur.
The results of the tests are displayed to the project members and maintainers, enabling them to identify problems and
react if errors occur.
## Using Codeberg's instance of Woodpecker CI
@ -22,23 +25,32 @@ After submitting, a Codeberg volunteer will review your request and grant you ac
In order to ensure a fast approval,
please take a minute to read about [the criteria that your project has to adhere to](https://codeberg.org/Codeberg-e.V./requests#woodpecker-ci).
If your request gets approved, you will be able to login to [ci.codeberg.org](https://ci.codeberg.org) via your Codeberg account.
To start builds for your repository, you must enable them in Woodpecker specifically using https://ci.codeberg.org/repos/add. Repositories owned by your codeberg account should automatically be available as options to select.
If your request gets approved, you will be able to login to [ci.codeberg.org](https://ci.codeberg.org)
via your Codeberg account.
To start builds for your repository, you must enable them in Woodpecker specifically using <https://ci.codeberg.org/repos/add>.
Repositories owned by your codeberg account should automatically be available as options to select.
### Caveats
For the usage of our Woodpecker instance, keep the following in mind:
- **CI access is provided as-is and might break at any time** and for an undefined period of time, due to server issues, for testing and maintenance purpose or human error.
- **Resource usage must be reasonable** for the intended use-case. CI requires substantial computing resources (cloning the repo and pulling the image, installing required tools, building and throwing everything away). Please try to ensure a good balance between code quality/automation and resource usage. Therefore, please consider twice how to create a good balance between ensuring code quality for your project and resource usage therefore.
- The CI service requires manual onboarding and Woodpecker has limited Role-Based Access Control (RBAC) capabilities, which will be a problem for projects with a team-based permission structure or many individual collaborators.
- **CI access is provided as-is and might break at any time** and for an undefined period of time, due to server issues,
for testing and maintenance purpose or human error.
- **Resource usage must be reasonable** for the intended use-case. CI requires substantial computing resources
(cloning the repo and pulling the image, installing required tools, building and throwing everything away).
Please try to ensure a good balance between code quality/automation and resource usage.
Therefore, please consider twice how to create a good balance between ensuring code quality for your project and
resource usage therefore.
- The CI service requires manual onboarding and Woodpecker has limited Role-Based Access Control (RBAC) capabilities,
which will be a problem for projects with a team-based permission structure or many individual collaborators.
Issues and general feedback should be reported in our
[dedicated Codeberg CI feedback repository](https://codeberg.org/Codeberg-CI/feedback).
### Usage
If you are curious about Woodpecker or are already using a third-party Woodpecker instance,
please consult [Woodpecker's documentation](https://woodpecker-ci.org/docs/intro). If you wish to see examples of integrating Woodpecker-CI with codeberg, please consult the [Codeberg-CI examples repository.](https://codeberg.org/Codeberg-CI/examples)
please consult [Woodpecker's documentation](https://woodpecker-ci.org/docs/intro).
If you wish to see examples of integrating Woodpecker-CI with codeberg, please consult the [Codeberg-CI examples repository.](https://codeberg.org/Codeberg-CI/examples)
### Custom Woodpecker Instances

104
content/codeberg-pages/examples/docs-as-code.md
View file

@ -6,60 +6,85 @@ eleventyNavigation:
order: 100
---
Docs-as-code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase, i.e. integrating the documentation process in the toolchains and workflows used by software development teams.
Docs-as-code (also known as "Documentation as Code") refers to the concept of treating documentation as a codebase,
i.e. integrating the documentation process in the toolchains and workflows used by software development teams.
Docs-as-code involves using version control systems such as Git for your documentation projects and authoring your content with plain text markup languages such as Markdown or reStructuredText, among other things.
Docs-as-code involves using version control systems such as Git for your documentation projects and authoring your content
with plain text markup languages such as Markdown or reStructuredText, among other things.
To find out more about docs-as-code, head over to [its website](https://docs-as-co.de/).
Whether you are a single technical communicator or a member of a larger documentation team, you can perfectly apply the docs-as-code approach to your documentation projects.
Whether you are a single technical communicator or a member of a larger documentation team, you can perfectly apply the
docs-as-code approach to your documentation projects.
This guide will show you how to implement docs-as-code on a Linux machine using [Sphinx](https://www.sphinx-doc.org/en/master/) as a documentation generator, [Git](https://ka2in.codeberg.page/gitinminutes.html) as a version control system and [Codeberg Pages](https://docs.codeberg.org/codeberg-pages/) as static site hosting.
This guide will show you how to implement docs-as-code on a Linux machine using [Sphinx](https://www.sphinx-doc.org/en/master/)
as a documentation generator, [Git](https://ka2in.codeberg.page/gitinminutes.html) as a version control system
and [Codeberg Pages](https://docs.codeberg.org/codeberg-pages/) as static site hosting.
{% admonition "info" "Note" %}
Despite the fact that we are using Sphinx in this particular case, you can easily apply these instructions to any static site generator (SSG) such as [Eleventy](https://www.11ty.dev/) or [Hugo](https://gohugo.io/).
Despite the fact that we are using Sphinx in this particular case, you can easily apply these instructions to any static
site generator (SSG) such as [Eleventy](https://www.11ty.dev/) or [Hugo](https://gohugo.io/).
{% endadmonition %}
## Building documentation with Sphinx
Initially developed to generate Python documentation, Sphinx is now widely used by technical communicators and software developers to create technical and software documentation.
Initially developed to generate Python documentation, Sphinx is now widely used by technical communicators and software
developers to create technical and software documentation.
Sphinx uses [reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) as a markup language to generate documentation content. Among further advantages, Sphinx allows you to produce your documentation in different formats, including HTML, LaTeX and ePub. You can also use one of the multiple extensions developed by the community to extend its functionality.
Sphinx uses [reStructuredText](https://docutils.sourceforge.io/docs/user/rst/quickref.html) as a markup language
to generate documentation content.
Among further advantages, Sphinx allows you to produce your documentation in different formats,
including HTML, LaTeX and ePub.
You can also use one of the multiple extensions developed by the community to extend its functionality.
### Setting up the project
To begin setting up your project, you will first need an account on Codeberg. If you don't already have one, follow the instructions provided under [Your First Steps on Codeberg](https://docs.codeberg.org/getting-started/first-steps/).
To begin setting up your project, you will first need an account on Codeberg.
If you don't already have one, follow the instructions provided under [Your First Steps on Codeberg](https://docs.codeberg.org/getting-started/first-steps/).
This guide assumes that you already have Git installed on your machine. If you don't, you can install git as described in the article [Install Git](https://docs.codeberg.org/getting-started/install-git/).
This guide assumes that you already have Git installed on your machine.
If you don't, you can install git as described in the article [Install Git](https://docs.codeberg.org/getting-started/install-git/).
For the purpose of this guide, we will start a documentation project from scratch using an empty repository. To create a new empty repository and clone it to your local workspace, follow the steps described in the article [Your First Repository](https://docs.codeberg.org/getting-started/first-repository/) as well as the instructions provided under "Option A: Clone the newly created, empty repository" within the same article.
For the purpose of this guide, we will start a documentation project from scratch using an empty repository.
To create a new empty repository and clone it to your local workspace,
follow the steps described in the article [Your First Repository](https://docs.codeberg.org/getting-started/first-repository/)
as well as the instructions provided under "Option A: Clone the newly created, empty repository" within the same article.
### Creating a Python virtual environment
A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on your projects. In other words, setting up a virtual environment for your project allows you to run an instance of the Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all these components inside that environment.
A "virtual" isolated environment comes in very handy to eliminate the risk of any broken dependencies while working on
your projects. In other words, setting up a virtual environment for your project allows you to run an instance of the
Python interpreter with a particular package set and a specific configuration while ensuring compatibility between all
these components inside that environment.
Before starting, you should make sure that you have pip and Python 3 installed on your machine. To check, type the following commands in your terminal:
Before starting, you should make sure that you have pip and Python 3 installed on your machine.
To check, type the following commands in your terminal:
```bash
$ pip --version
$ python3 --version
```
If pip and Python are not installed on your Linux machine, please follow the steps described in the articles [pip Installation](https://pip.pypa.io/en/latest/installation/) and [Installing Python 3 on Linux](https://docs.python-guide.org/starting/install3/linux/) respectively.
If pip and Python are not installed on your Linux machine, please follow the steps described in the articles [pip Installation](https://pip.pypa.io/en/latest/installation/)
and [Installing Python 3 on Linux](https://docs.python-guide.org/starting/install3/linux/) respectively.
Depending on your Python version, you will need to install a compatible virtual environment manager, i.e. either "venv" for Python >= 3.3, or "virtualenv" for older Python versions.
Depending on your Python version, you will need to install a compatible virtual environment manager,
i.e. either "venv" for Python >= 3.3, or "virtualenv" for older Python versions.
{% admonition "warning" %}
Please note that Python2 has reached its EOL (End of Life) on January 1st 2020, which means that it is no longer receiving any security updates.
Please note that Python2 has reached its EOL (End of Life) on January 1st 2020, which means that it is no longer
receiving any security updates.
If you are using Python 3.3 or higher, you do not need to install the "venv" module, since it is already available in your Python standard library.
If you are using Python 3.3 or higher, you do not need to install the "venv" module, since it is already available in
your Python standard library.
{% endadmonition %}
The next step is to create a virtual environment. To do so, navigate to the folder where you have cloned the repository described under the section [Setting up the project](#setting-up-the-project):
The next step is to create a virtual environment. To do so, navigate to the folder where you have cloned the repository
described under the section [Setting up the project](#setting-up-the-project):
```bash
$ cd ~/repositories/foobar
@ -70,13 +95,15 @@ You can replace the second argument "env" with any other name your like. This wi
{% admonition "warning" %}
Use a **`.gitignore`** file to exclude your virtual environment directory from your version control system. To ignore the entire "env" folder, include the corresponding path and append a **`/`** at its end, e.g. **`env/`**.
Use a **`.gitignore`** file to exclude your virtual environment directory from your version control system.
To ignore the entire "env" folder, include the corresponding path and append a **`/`** at its end, e.g. **`env/`**.
{% endadmonition %}
### Activating the virtual environment
Before you begin performing any tasks on your project, you must activate your virtual environment by running the following command:
Before you begin performing any tasks on your project, you must activate your virtual environment by running the
following command:
```bash
$ . env/bin/activate
@ -102,7 +129,10 @@ $ deactivate
### Installing Sphinx in your virtual environment
If you have followed the steps described up to this point, your local repository should now contain your virtual environment's folder **`env`** in addition to the hidden **`.git`** directory and the **`.gitignore`** file that we have already described at the end of the section [Creating a Python virtual environment](#creating-a-python-virtual-environment), e.g.:
If you have followed the steps described up to this point, your local repository should now contain your virtual
environment's folder **`env`** in addition to the hidden **`.git`** directory and the **`.gitignore`** file that we have
already described at the end of the section [Creating a Python virtual environment](#creating-a-python-virtual-environment),
e.g.:
```
├── myproject
@ -112,7 +142,8 @@ If you have followed the steps described up to this point, your local repository
```
<a name="mydocs"></a>
You will now create an empty directory then navigate to it. For the purpose of this guide, we will call our directory `mydocs`. You can choose any name you'd like:
You will now create an empty directory then navigate to it. For the purpose of this guide, we will call our directory
`mydocs`. You can choose any name you'd like:
```bash
$ mkdir mydocs
@ -148,7 +179,10 @@ Once Sphinx is installed on your virtual environment, type the following command
```
You will then be asked to answer a series of questions regarding the configuration of your project.
Confirm that you want to **`Separate source and build directories`**. For the rest of the questions, keep pressing **Enter** to accept the default values and fill out the requested fields until you reach the question **`autodoc: automatically insert docstrings from modules`**, then choose **"y" (yes)**. Keep pressing **Enter** again until you reach the question **`Create Makefile?`** and select **"y" (yes)**.
Confirm that you want to **`Separate source and build directories`**.
For the rest of the questions, keep pressing **Enter** to accept the default values and fill out the requested fields
until you reach the question **`autodoc: automatically insert docstrings from modules`**, then choose **"y" (yes)**.
Keep pressing **Enter** again until you reach the question **`Create Makefile?`** and select **"y" (yes)**.
If you now run the `tree` command from your `mydocs` folder, you should get the following output:
@ -168,7 +202,8 @@ Congratulations! 🎉 You have just finished installing Sphinx on your Linux mac
### Running a local HTTP server using Python
To set up a local testing server for your documentation project, you can use the Python module **`http.server`**. To do so, you will first have to build the HTML resources for the initial test by running the command:
To set up a local testing server for your documentation project, you can use the Python module **`http.server`**.
To do so, you will first have to build the HTML resources for the initial test by running the command:
<a name="build"></a>
@ -194,7 +229,8 @@ Once there, run the local python server with the command:
{% endadmonition %}
To access the default **`index.html`** file, type **`http://localhost:8080`** in your favorite browser. You should then see the default welcome page.
To access the default **`index.html`** file, type **`http://localhost:8080`** in your favorite browser.
You should then see the default welcome page.
### Creating files with reStructuredText and checking the output
@ -205,9 +241,14 @@ You can start creating your own content by making a new reStructuredText file (.
(.venv) $ touch mynewfile.rst
```
You have just created an empty ".rst" file with the **`touch`** command. An ".rst" file is simply a plain text file that is written with reStructuredText as a markup language. To learn about how to use reStructuredText, follow the instructions provided in the article [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
You have just created an empty ".rst" file with the **`touch`** command. An ".rst" file is simply a plain text file that
is written with reStructuredText as a markup language.
To learn about how to use reStructuredText, follow the instructions provided in the article [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
You will be more productive in your writing if you use a text editor that supports syntax highlighting such as [Emacs](https://www.gnu.org/software/emacs/download.html) or [VSCodium](https://vscodium.com/). Linux offers plenty of powerful text editors that support syntax highlighting and other advanced features for coding and authoring tasks.
You will be more productive in your writing if you use a text editor that supports syntax highlighting such as
[Emacs](https://www.gnu.org/software/emacs/download.html) or [VSCodium](https://vscodium.com/).
Linux offers plenty of powerful text editors that support syntax highlighting and other advanced features for coding and
authoring tasks.
{% admonition "info" %}
@ -215,8 +256,13 @@ Whenever you create a new .rst file, you must add it manually to the `toctree` o
{% endadmonition %}
The toctree directive (toc stands for Table of Contents) inserts a tree that connects the different ".rst" files located in your source directory with each other. Read the article [Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive) to learn more about the toctree directive.
The toctree directive (toc stands for Table of Contents) inserts a tree that connects the different ".rst" files located
in your source directory with each other.
Read the article [Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive)
to learn more about the toctree directive.
Once you have added an .rst file to the `toctree`, you can check the output at any time by running the [sphinx-build](#running-a-local-http-server-using-python) command illustrated above, then refreshing your local testing server.
Once you have added an .rst file to the `toctree`, you can check the output at any time by running the [sphinx-build](#running-a-local-http-server-using-python)
command illustrated above, then refreshing your local testing server.
If you are satisfied with the result on your local development environment, you can publish the content on Codeberg Pages. To find out how to do this, read the article [Pushing output from SSGs into Codeberg Pages](https://docs.codeberg.org/codeberg-pages/pushing-output/).
If you are satisfied with the result on your local development environment, you can publish the content on Codeberg Pages.
To find out how to do this, read the article [Pushing output from SSGs into Codeberg Pages](https://docs.codeberg.org/codeberg-pages/pushing-output/).

22
content/codeberg-pages/index.md
View file

@ -8,13 +8,15 @@ eleventyNavigation:
{% admonition "Warning" %}
Codeberg Pages is currently provided with a best effort approach. To be exact, the software behind this feature is currently in [maintenance mode](https://codeberg.org/Codeberg/pages-server/issues/399).
Codeberg Pages is currently provided with a best effort approach.
To be exact, the software behind this feature is currently in [maintenance mode](https://codeberg.org/Codeberg/pages-server/issues/399).
Please do not rely on it for critical websites, as we can't guarantee high availability like some other providers do.
{% endadmonition %}
Codeberg Pages allows you to easily publish static websites with a human-friendly address (`{username}.codeberg.page`) via Git on Codeberg.
Codeberg Pages allows you to easily publish static websites with a human-friendly address (`{username}.codeberg.page`)
via Git on Codeberg.
Follow these simple steps below to get started, or check out the advanced usage below.
@ -58,20 +60,26 @@ See also:
The Codeberg Pages server responds to four different URLs:
- `https://raw.codeberg.page/username/reponame/`: raw content, uses correct MIME types (HTML is forbidden though) and is accessible with CORS.
- `https://raw.codeberg.page/username/reponame/`: raw content, uses correct MIME types (HTML is forbidden though)
and is accessible with CORS.
- `https://username.codeberg.page`: user page, points the default branch of a user's or organization's `pages` repository
- `https://username.codeberg.page/reponame/`: repo page, points to the `pages` branch of the repository
- `https://example.org`: custom domain, points to a repo of choice as outlined below
In all cases, you can append a branch using an `@` (e.g. `https://username.codeberg.page/@develop/README.md`). If the branch name contains a slash (`/`), they need to be replaced with a tilde (`~`) (e.g. the branch `docs/develop` can be accessed via `https://username.codeberg.page/@docs~develop/README.md`).
In all cases, you can append a branch using an `@` (e.g. `https://username.codeberg.page/@develop/README.md`).
If the branch name contains a slash (`/`), they need to be replaced with a tilde (`~`) (e.g. the branch `docs/develop`
can be accessed via `https://username.codeberg.page/@docs~develop/README.md`).
## Do you have questions, feedback or have you found a bug?
The source code for Codeberg Pages is maintained over at the [Pages Server repository](https://codeberg.org/Codeberg/pages-server); feel free to head there to provide some feedback, suggestions, bug reports or even patches.
If you need general community support or have questions, [Codeberg/Community](https://codeberg.org/Codeberg/Community) is a better place to ask, as more people will be watching there to help you out!
The source code for Codeberg Pages is maintained over at the [Pages Server repository](https://codeberg.org/Codeberg/pages-server);
feel free to head there to provide some feedback, suggestions, bug reports or even patches.
If you need general community support or have questions, [Codeberg/Community](https://codeberg.org/Codeberg/Community)
is a better place to ask, as more people will be watching there to help you out!
We really appreciate your contribution.
## Installing Pages for your own Forgejo instance
Codeberg Pages works with any Forgejo host out there. So if you are running your own Forgejo, you can absolutely run it yourself and help with the development.
Codeberg Pages works with any Forgejo host out there. So if you are running your own Forgejo, you can absolutely run it
yourself and help with the development.
Check out the [Pages Server repository](https://codeberg.org/Codeberg/pages-server) for more information.

24
content/codeberg-pages/pushing-output.md
View file

@ -8,23 +8,30 @@ eleventyNavigation:
order: 101
---
If you are using a static site generator (SSG) and are satisfied with the result of your project on your local development environment, you can push the files to your Codeberg Pages repository.
If you are using a static site generator (SSG) and are satisfied with the result of your project on your local development
environment, you can push the files to your Codeberg Pages repository.
To begin with, we will have two separate repositories, both locally and on Codeberg:
- A main repository for the source files, i.e. where the source files related to your main project will be located. We will refer to this repository as the `source` repository. This repository is the one associated with your [mydocs](/codeberg-pages/examples/docs-as-code/#mydocs) folder.
- A main repository for the source files, i.e. where the source files related to your main project will be located.
We will refer to this repository as the `source` repository.
This repository is the one associated with your [mydocs](/codeberg-pages/examples/docs-as-code/#mydocs) folder.
- A second repository for Codeberg pages that we will call the `pages` repository. This repository will only contain the files available in the `html` folder located under docs/build/html.
- A second repository for Codeberg pages that we will call the `pages` repository.
This repository will only contain the files available in the `html` folder located under docs/build/html.
{% admonition "warning" %}
The `pages` repository **must** be public, as Codeberg Pages will directly fetch the files from the repository, just like an ordinary user would.
The `pages` repository **must** be public, as Codeberg Pages will directly fetch the files from the repository,
just like an ordinary user would.
{% endadmonition %}
{% admonition "info" %}
For the purpose of this guide, we have chosen to use two separate folders/repositories. However, you may want to have a different setup that involves creating a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) instead of having folders and repositories in separate locations. With a submodule, your configuration may look like so:
For the purpose of this guide, we have chosen to use two separate folders/repositories.
However, you may want to have a different setup that involves creating a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
instead of having folders and repositories in separate locations. With a submodule, your configuration may look like so:
```
├── sources --> This is a git repo
@ -74,8 +81,11 @@ $ git push origin HEAD:your-remote-branch-name
{% admonition "info" "Note" %}
Replace `your-remote-branch-name` with the name of your remote branch. It is recommended to initially push your commits to a branch other than the default branch. Once you have made sure everything went smoothly, you can then make a pull request to merge it into the default branch. To learn more about pull requests, read the article [Pull requests and Git flow](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/).
Replace `your-remote-branch-name` with the name of your remote branch. It is recommended to initially push your commits
to a branch other than the default branch. Once you have made sure everything went smoothly, you can then make a pull
request to merge it into the default branch. To learn more about pull requests, read the article [Pull requests and Git flow](https://docs.codeberg.org/collaborating/pull-requests-and-git-flow/).
{% endadmonition %}
You should now be able to access your content by visiting https://{username}.codeberg.page. You can find more information in the [Codeberg Pages](/codeberg-pages/) section.
You should now be able to access your content by visiting https://{username}.codeberg.page.
You can find more information in the [Codeberg Pages](/codeberg-pages/) section.

11
content/codeberg-pages/troubleshooting.md
View file

@ -8,7 +8,11 @@ eleventyNavigation:
## My web browser displays a security warning when I try to access my Codeberg Pages.
If your user name or repository name contains a dot, your Codeberg Pages URL (https://user.name.codeberg.page or https://repo.sitory.username.codeberg.page) contains a sub-sub-domain which does not work with Let's Encrypt wildcard certificates. Use the alternative URL https://pages.codeberg.org/user.name/ as a workaround or rename you repository (e.g. replace `.` by `_`).
If your user name or repository name contains a dot, your Codeberg Pages URL (<https://user.name.codeberg.page>
or <https://repo.sitory.username.codeberg.page>)
contains a sub-sub-domain which does not work with Let's Encrypt wildcard certificates.
Use the alternative URL <https://pages.codeberg.org/user.name/> as a workaround or rename you repository
(e.g. replace `.` by `_`).
## My content is not updated
@ -18,4 +22,7 @@ This is done to improve performance, reduce cost and server load, and save energ
## Cloudflare and Codeberg Pages
It is important that when you use [Cloudflare](https://cloudflare.com) to manage your Domain's DNS records, that every DNS record used for Codeberg Pages needs to be set to **DNS only** (Have a gray cloud). This ensures that Codeberg pages can properly handle everything necessary for your site such as SSL-Certificate and redirects from other (sub-)domains.
It is important that when you use [Cloudflare](https://cloudflare.com) to manage your Domain's DNS records,
that every DNS record used for Codeberg Pages needs to be set to **DNS only** (Have a gray cloud).
This ensures that Codeberg pages can properly handle everything necessary for your site such as SSL-Certificate and
redirects from other (sub-)domains.

59
content/codeberg-pages/using-custom-domain.md
View file

@ -6,36 +6,48 @@ eleventyNavigation:
order: 10
---
Instead of using the `codeberg.page` domain, you can also purchase your own domain from a domain registrar of your choice and configure it to serve content from Codeberg Pages.
Instead of using the `codeberg.page` domain, you can also purchase your own domain from a domain registrar of your choice
and configure it to serve content from Codeberg Pages.
{% admonition "warning" "Known pitfalls for failed certificate errors" %}
If you have a [CAA record](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization#Record) configured, you must [explicitly allow Let's Encrypt in your CAA record](https://letsencrypt.org/docs/caa/).
If you have a [CAA record](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization#Record) configured,
you must [explicitly allow Let's Encrypt in your CAA record](https://letsencrypt.org/docs/caa/).
The value of the CAA record would look like `letsencrypt.org;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/292520050;validationmethods=tls-alpn-01,http-01`.
{% endadmonition %}
For custom domains, two things are required:
- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages. The file should contain a list of _all_ domains that shall be usable to access that repository, according to the following rules:
- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages.
The file should contain a list of _all_ domains that shall be usable to access that repository,
according to the following rules:
- One domain per line, you can leave lines empty and comment out lines with `#`.
- The first domain is the main domain, all other domains in the file will be redirected to the first one.
- The rest of the list includes all relevant `*.codeberg.page` domains for the specific repository.
- a [DNS record](https://en.wikipedia.org/wiki/Domain_Name_System#Address_resolution_mechanism) pointing to one of the following targets, depending on where your static files reside:
- a [DNS record](https://en.wikipedia.org/wiki/Domain_Name_System#Address_resolution_mechanism) pointing to one of the
following targets, depending on where your static files reside:
<br />
{% admonition "question" "Why do I need all of these DNS records?" %}
To understand how the Pages server serves content, you need to know that a user browsing your custom domain just sends "Hey, I want to see `yourdomain.com`" to the server. But the server might not know that it is responsible for `yourdomain.com` and it cannot just serve all domains in the world. So to find out if the server is responsible for `yourdomain.com` it will check the DNS entries of `yourdomain.com`. If it returns something with `codeberg.page` (according to the domain schemes mentioned below) then it knows which respository to check for the `.domains` file and your content.
To understand how the Pages server serves content, you need to know that a user browsing your custom domain just sends
"Hey, I want to see `yourdomain.com`" to the server.
But the server might not know that it is responsible for `yourdomain.com` and it cannot just serve all domains in the world.
So to find out if the server is responsible for `yourdomain.com` it will check the DNS entries of `yourdomain.com`.
If it returns something with `codeberg.page` (according to the domain schemes mentioned below) then it knows which
respository to check for the `.domains` file and your content.
{% endadmonition %}
## Setting the DNS record
There are several ways DNS records for your website can be setup in order to tell the Pages server your repository location. For all of the options it is important that the Pages server knows where to look for the `.domains` file and your content. Depending on from where you want to serve your files, there is a naming scheme for the domain:
There are several ways DNS records for your website can be setup in order to tell the Pages server your repository location.
For all of the options it is important that the Pages server knows where to look for the `.domains` file and your content.
Depending on from where you want to serve your files, there is a naming scheme for the domain:
<table class="table">
<thead>
@ -58,21 +70,25 @@ There are several ways DNS records for your website can be setup in order to tel
</tbody>
<table>
_We assume for the following description, that you want to serve your website with and without www in front. If you are on a subdomain already (like myproject.yourdomain.com), you can skip the `www.yourdomain.com` CNAME entry._
_We assume for the following description, that you want to serve your website with and without www in front.
If you are on a subdomain already (like myproject.yourdomain.com), you can skip the `www.yourdomain.com` CNAME entry._
{% admonition "Warning" %}
When setting up DNS records with many registrars, any domain added to the `Domain` or `Host` option is automatically appended onto the domain the records are being made for.
When setting up DNS records with many registrars, any domain added to the `Domain` or `Host` option is automatically
appended onto the domain the records are being made for.
For example, if your domain is `example.com`, entering `www` will mean the record refers to `www.example.com`.
Therefore, in this guide, you may need to replace references to just your domain name (e.g. `example.com`) with `@` and `anything.example.com` (i.e. any subdomain) with just `anything`.
Therefore, in this guide, you may need to replace references to just your domain name (e.g. `example.com`) with `@` and
`anything.example.com` (i.e. any subdomain) with just `anything`.
{% endadmonition %}
**Option 1: CNAME record**
The easiest and recommended way is to just setup a CNAME record for your domain, pointing to the mentioned above locations. In the end, it should look like this:
The easiest and recommended way is to just setup a CNAME record for your domain, pointing to the mentioned above locations.
In the end, it should look like this:
<table class="table">
<thead>
@ -93,7 +109,8 @@ The easiest and recommended way is to just setup a CNAME record for your domain,
{% admonition "Warning" %}
With a CNAME record everything on this domain is delegated to `codeberg.page`, which means you cannot setup your own email address with this method.
With a CNAME record everything on this domain is delegated to `codeberg.page`, which means you cannot setup your own
email address with this method.
If you need email or others services, you have to use one of the remaining options.
@ -103,8 +120,12 @@ If you need email or others services, you have to use one of the remaining optio
If you cannot use a CNAME record to configure the target you can use this method, which needs two entries instead of one.
- First you need to specify which server should be serving your website. Similar to CNAME you can use an `ALIAS record`. The [difference](https://www.ecosia.org/search?q=cname%20vs%20alias%20record) between an CNAME record is, that the DNS server directly responds with the ip address and not the `codeberg.page` domain. Therefore you need to add a second entry, so that the pages server knows what to serve under this domain.
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
- First you need to specify which server should be serving your website. Similar to CNAME you can use an `ALIAS record`.
The [difference](https://www.ecosia.org/search?q=cname%20vs%20alias%20record) between an CNAME record is,
that the DNS server directly responds with the ip address and not the `codeberg.page` domain.
Therefore you need to add a second entry, so that the pages server knows what to serve under this domain.
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository
location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
In the end it should look like this:
@ -130,10 +151,12 @@ In the end it should look like this:
If your service provider does not support `ALIAS records` you can also use `A records` and `AAAA records` instead.
- First you need to specify which server should be serving your website. You can do this by setting an `A record` for IPv4 and an `AAAA record` for IPv6 which contains the ip address of the Codeberg Pages server. The servers' ip addresses are:
- First you need to specify which server should be serving your website. You can do this by setting an `A record` for IPv4
and an `AAAA record` for IPv6 which contains the ip address of the Codeberg Pages server. The servers' ip addresses are:
- `A record` which contains the IPv4 value `217.197.84.141`
- `AAAA record` which contains the IPv6 value `2a0a:4580:103f:c0de::2`
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
- Second, you need to setup a `TXT record` which contains the information from the `CNAME entry` which is your repository
location as mentioned above. For example `[[branch.]repo.]user.codeberg.page`.
In the end, it should look like this:
@ -167,7 +190,8 @@ The following sub-sections include a few examples of the different alternatives,
- `frida/pages`, with a _Personal_ static site inside branch `pages`;
- `frida/colormix`, with a _Project_ site (again, inside branch `pages`).
All considerations regarding a _Personal_ site also apply to an _Organization_ site, so these two cases will be addressed together.
All considerations regarding a _Personal_ site also apply to an _Organization_ site, so these two cases will be
addressed together.
### Personal (or Organization) site, third level domain
@ -257,7 +281,8 @@ In this case, we want our _Project_ pages available at the URL `https://example.
{% admonition "info" "Note" %}
This would be incompatible with using the apex `example.com` for other purposes, e.g. for the _Personal_/_Organization_ example discussed before.
This would be incompatible with using the apex `example.com` for other purposes, e.g. for the _Personal_/_Organization_
example discussed before.
{% endadmonition %}

22
content/codeberg-translate/introduction-to-weblate.md
View file

@ -5,17 +5,23 @@ eleventyNavigation:
parent: CodebergTranslate
---
Codeberg hosts it's own [Weblate](https://weblate.org) Instance to help Codeberg users localize their software. This service is called [Codeberg Translate](https://translate.codeberg.org/)
Codeberg hosts it's own [Weblate](https://weblate.org) Instance to help Codeberg users localize their software.
This service is called [Codeberg Translate](https://translate.codeberg.org/)
## What is Weblate?
When you write software, a website, documentation or something else, you may want to translate it, so it can be used by others, who do not speak English. But you are facing a problem: You don't speak all languages in the world.
Thankfully, there are a lot of native speakers who want to translate things in their language. But not all of those translators are coders, so you can't expect them to go to your your repository, fork it, edit the code to add the language
and create a pull request. To solve this problem, software like Weblate exists. It provides a easy to use GUI for translators. They just see the English (or the other language you use as a base) texts and can write the translation. They don't need
to take a look at the code at all, so everyone, not only coders, can translate your software.
When you write software, a website, documentation or something else, you may want to translate it, so it can be used by
others, who do not speak English. But you are facing a problem: You don't speak all languages in the world.
Thankfully, there are a lot of native speakers who want to translate things in their language. But not all of those
translators are coders, so you can't expect them to go to your your repository, fork it, edit the code to add the language
and create a pull request. To solve this problem, software like Weblate exists. It provides a easy to use GUI for translators.
They just see the English (or the other language you use as a base) texts and can write the translation.
They don't need to take a look at the code at all, so everyone, not only coders, can translate your software.
## Do I need to change my code?
You can't give Weblate your code and it magically makes it translatable. You need to use an existing translation system such as gettext or Qt Linguist. Which one you should use depends on your used language and toolkit. Take a look at their
documentation to learn more. You should end up with a directory which contains the different translations. Each language should have its own file. e.g. `de.po` for gettext. After that you give Weblate a link to your repository and basically
just say, my translations are in this directory and I'm using this format. Weblate does the rest.
You can't give Weblate your code and it magically makes it translatable. You need to use an existing translation system
such as gettext or Qt Linguist. Which one you should use depends on your used language and toolkit.
Take a look at their documentation to learn more. You should end up with a directory which contains the different translations.
Each language should have its own file. e.g. `de.po` for gettext. After that you give Weblate a link to your repository
and basically just say, my translations are in this directory and I'm using this format. Weblate does the rest.

15
content/codeberg-translate/manual-component-configuration.md
View file

@ -5,7 +5,8 @@ eleventyNavigation:
parent: CodebergTranslate
---
This article will teach how, how to manually configure a Weblate component, in case, it's not working automatically. You will not need this in most cases.
This article will teach how, how to manually configure a Weblate component, in case, it's not working automatically.
You will not need this in most cases.
## What is monolingual and bilingual?
@ -27,14 +28,18 @@ With Monolingual, you have a extra translation file for your source language.
## Where can I find these Options:
When creating a new Component, you will land on a Page where you can enter them. For existing Components, go to the Component Manage>Settings>Files.
When creating a new Component, you will land on a Page where you can enter them.
For existing Components, go to the Component Manage>Settings>Files.
## Configuration options
You have the following options to configure the component:
File format: Choose one of the available formats
File mask: This is the path, in which your translations will be placed `*` is the placeholder for the language. e.g. if you enter `translations/*.ts`, a German translation would be placed as `translations/de.ts`.
Monolingual base language file: If you have a Monolingual format, enter the path to your source file here. If not, leave empty.
Edit base file: If you enable this, the source file can be edited in Weblate. If not ticked, it is read only in Weblate. Only available for monolingual formats.
File mask: This is the path, in which your translations will be placed `*` is the placeholder for the language.
e.g. if you enter `translations/*.ts`, a German translation would be placed as `translations/de.ts`.
Monolingual base language file: If you have a Monolingual format, enter the path to your source file here.
If not, leave empty.
Edit base file: If you enable this, the source file can be edited in Weblate. If not ticked, it is read only in Weblate.
Only available for monolingual formats.
Adding new translation: You can choose, what happens, if a User wan's to add a new language. The Options should be self-explanatory.
Template for new translations: If you choose "Create new language file" in the Box above, this file will be used as a template.

33
content/collaborating/citable-code.md
View file

@ -5,39 +5,54 @@ eleventyNavigation:
parent: Collaborating
---
The easiest way to refer to your code is to send/post the URL of your repository. However, if you need to reliably refer to a specific version of your code in the long run, for example for scientific writing, this is not really viable, because URLs can change.
Another possibility is to download your repository as a ZIP or TAR.GZ archive (see section Clone in [Clone & Commit via Web](/git/clone-commit-via-web)) and share this file.
The third option, which actually complements the second, is to assign a [Digital Object Identifier](https://www.doi.org/) (DOI) to your code. Having a DOI for your code means that everybody can cite your code using this _standard_ and _permanent identifier_. Assigning a DOI for citation is routine in the academic world.
The easiest way to refer to your code is to send/post the URL of your repository.
However, if you need to reliably refer to a specific version of your code in the long run, for example for scientific
writing, this is not really viable, because URLs can change.
Another possibility is to download your repository as a ZIP or TAR.GZ archive (see section Clone in [Clone & Commit via Web](/git/clone-commit-via-web))
and share this file.
The third option, which actually complements the second, is to assign a [Digital Object Identifier](https://www.doi.org/)
(DOI) to your code. Having a DOI for your code means that everybody can cite your code using this _standard_
and _permanent identifier_.
Assigning a DOI for citation is routine in the academic world.
This page will show you how to do just that. The process can be decomposed in four steps.
## Create a release of your repository
Creating a release is optional, but recommended. A release will make it clear what version of your code you want to share/cite. Any further edits to your code will not be included in the release. In other words, it's good practice to share/cite a release with fixed code rather than the always changing code of your repository.
Creating a release is optional, but recommended. A release will make it clear what version of your code you want to share/cite.
Any further edits to your code will not be included in the release.
In other words, it's good practice to share/cite a release with fixed code rather than the always changing code of your repository.
You can find instructions on the [Tags and Releases article](/git/using-tags/#creating-tags-and-releases).
## Download the ZIP archive
If you created a release, download the ZIP archive of the source code on the `Releases` tab of your repository, as shown in the previous screenshot.
If you created a release, download the ZIP archive of the source code on the `Releases` tab of your repository,
as shown in the previous screenshot.
If not, you can simply download the ZIP archive of the repository (see section Clone in [Clone & Commit via Web](/git/clone-commit-via-web)).
## Upload the ZIP archive to an online repository
There are many online repositories made specifically for research, e.g. [Zenodo](https://zenodo.org/), [Figshare](https://figshare.com/), [Dryad](https://datadryad.org/), and [OSF](https://osf.io/). Others might be more appropriate for other uses.
There are many online repositories made specifically for research, e.g. [Zenodo](https://zenodo.org/), [Figshare](https://figshare.com/),
[Dryad](https://datadryad.org/), and [OSF](https://osf.io/).
Others might be more appropriate for other uses.
Upload the ZIP archive to one of them, and follow the steps there to assign a DOI. Be sure that you add the URL of your Codeberg repository in the information of the record on the online repository, so that everyone accessing the record can easily find your Codeberg repository (and you!). In general, add as much information as applicable.
Upload the ZIP archive to one of them, and follow the steps there to assign a DOI. Be sure that you add the URL of your
Codeberg repository in the information of the record on the online repository, so that everyone accessing the record can
easily find your Codeberg repository (and you!). In general, add as much information as applicable.
{% admonition "info" %}
It should be possible to write an integration between Codeberg and one of the DOI repositories to make citing code a lot smoother. If you happen to be interested, you may want to have a look at [#295](https://codeberg.org/Codeberg/Community/issues/295).
It should be possible to write an integration between Codeberg and one of the DOI repositories to make citing code a lot
smoother. If you happen to be interested, you may want to have a look at [#295](https://codeberg.org/Codeberg/Community/issues/295).
{% endadmonition %}
## Share the DOI
Finally, get the DOI from the online repository. This is the permanent URL you can share and use for citation in scientific writing.
Finally, get the DOI from the online repository.
This is the permanent URL you can share and use for citation in scientific writing.
A DOI has the form `https://doi.org/repoID/recordID`. It has three parts:

75
content/collaborating/create-organization.md
View file

@ -8,9 +8,13 @@ eleventyNavigation:
## What is an organization?
An organization is a group of users that have access to a shared account. As such, they can all access the different repositories of the organization. An organization can be composed of several teams, each having a defined role in the project's development and also different access rights. This makes organizations an easy and powerful tool to collaborate on a project.
An organization is a group of users that have access to a shared account.
As such, they can all access the different repositories of the organization. An organization can be composed of several teams,
each having a defined role in the project's development and also different access rights.
This makes organizations an easy and powerful tool to collaborate on a project.
Everyone can create organizations on Codeberg for free. The following sections will show you how to create and manage an organization.
Everyone can create organizations on Codeberg for free. The following sections will show you how to create and manage an
organization.
{% admonition "info" %}
@ -24,7 +28,9 @@ On your Dashboard, click on the `+` next to your avatar and select `New Organiza
<img src="/images/collaborating/create-organization/new-orga.png" alt="new-orga">
In the new page, choose a name for your organization (here we choose `PolarClub`) and select its visibility. Finally, choose what the administrators of repositories can do; if the box is ticked, repository administrators will be able to grant any team access to the repository (see [Access rights](#access-rights) below for details on repository administrators).
In the new page, choose a name for your organization (here we choose `PolarClub`) and select its visibility.
Finally, choose what the administrators of repositories can do; if the box is ticked, repository administrators will be
able to grant any team access to the repository (see [Access rights](#access-rights) below for details on repository administrators).
Confirm by clicking `Create Organization`:
@ -34,7 +40,8 @@ You're now directed to the organization's dashboard.
## Switch between your personal account and the organization
On the dashboard, click on the avatar on the left and select the context (personal account or organization) you want to work with. Alternatively, switch between your repositories or your organizations tabs on the right side.
On the dashboard, click on the avatar on the left and select the context (personal account or organization) you want
to work with. Alternatively, switch between your repositories or your organizations tabs on the right side.
<img src="/images/collaborating/create-organization/dashboard.png" alt="dashboard">
@ -48,7 +55,9 @@ If you click on the `View [organization]` (here `PolarClub`, you'll be directed
<img src="/images/collaborating/create-organization/orga.png" alt="orga">
From here, you can access all repositories (there's currently none here) and create new ones. There's a list of all the members (`People`) and teams; in this example, there is only one member (Knut the polar bear), and one team (`Owners`) with one member (yourself) and no repositories.
From here, you can access all repositories (there's currently none here) and create new ones.
There's a list of all the members (`People`) and teams; in this example, there is only one member (Knut the polar bear),
and one team (`Owners`) with one member (yourself) and no repositories.
## Edit organization
@ -56,35 +65,49 @@ The cog next to the organization's name will lead you to its settings:
<img src="/images/collaborating/create-organization/cog.png" alt="cog">
This is where you can change general settings related to your organization, such as its name, avatar, website or visibility. You can also delete your organization, and access more advanced settings like organization webhooks:
This is where you can change general settings related to your organization, such as its name, avatar, website or visibility.
You can also delete your organization, and access more advanced settings like organization webhooks:
<img src="/images/collaborating/create-organization/orga-settings.png" alt="orga-settings">
The `Name` of the organization is the name that will define the URLs of the organization and of all its repositories; it is recommended to keep it short. This name will also appear on the member's profiles (see [People](#people)). On the other hand, the `Full Name` is the name that will appear on the organization's home page.
The `Name` of the organization is the name that will define the URLs of the organization and of all its repositories;
it is recommended to keep it short. This name will also appear on the member's profiles (see [People](#people)).
On the other hand, the `Full Name` is the name that will appear on the organization's home page.
In the `Labels` tab, you can create labels that will be used across all repositories of this organization. This will help with issues and pull requests. The default label set is a good starting point.
In the `Labels` tab, you can create labels that will be used across all repositories of this organization.
This will help with issues and pull requests. The default label set is a good starting point.
In the top right corner, you have access to the members and teams of your organization. These can also be accessed from the organization's page.
In the top right corner, you have access to the members and teams of your organization. These can also be accessed from
the organization's page.
## Teams
The `Teams` tab gives you an overview of all the teams, their members and their number of repositories. You can also join a team from here if you have the permission to do so:
The `Teams` tab gives you an overview of all the teams, their members and their number of repositories.
You can also join a team from here if you have the permission to do so:
<img src="/images/collaborating/create-organization/teams.png" alt="teams">
When you create an organization, a team `Owners` is created and you are automatically added to this team. Members of the Owners' team have all permissions (see [Access rights](#access-rights) below for details).
When you create an organization, a team `Owners` is created and you are automatically added to this team.
Members of the Owners' team have all permissions (see [Access rights](#access-rights) below for details).
Click the `+ New Team` button to create a new team. Now, in the new page, you can set its name, permissions, and accessible repositories.
Click the `+ New Team` button to create a new team. Now, in the new page, you can set its name, permissions,
and accessible repositories.
<img src="/images/collaborating/create-organization/new-team.png" alt="new-team">
You can choose whether members of the team can only access some repositories explicitly added to the team, or whether they can access all repositories of the organization.
You can choose whether members of the team can only access some repositories explicitly added to the team, or whether
they can access all repositories of the organization.
You can also allow members to be able to create new repositories on behalf of the organization.
If you have allowed repository administrators to grant or remove access for teams (see [Create an Organization](#create-an-organization) above), they can do so in the `Settings → Collaborators` tab of the repository.
If you allow either `Read` or `Write` access, you can additionally set which sections of the repositories (code, issues, pull requests, releases and wiki) the members will have (read or write) access to. On the other hand, `Administrator Access` automatically grants read and write access to all sections; this part of the page is hidden in this case.
If you have allowed repository administrators to grant or remove access for teams (see [Create an Organization](#create-an-organization)
above), they can do so in the `Settings → Collaborators` tab of the repository.
If you allow either `Read` or `Write` access, you can additionally set which sections of the repositories
(code, issues, pull requests, releases and wiki) the members will have (read or write) access to.
On the other hand, `Administrator Access` automatically grants read and write access to all sections;
this part of the page is hidden in this case.
See the section [Access rights](#access-rights) below for details.
If you belong to the team `Owners`, you can edit teams. To do this, go to the `Teams` tab and click on the team you want to edit:
If you belong to the team `Owners`, you can edit teams.
To do this, go to the `Teams` tab and click on the team you want to edit:
<img src="/images/collaborating/create-organization/team-settings.png" alt="team-settings">
@ -97,9 +120,14 @@ On the `People` tab, you can get an overview of all the people who belong to you
<img src="/images/collaborating/create-organization/people.png" alt="people">
Somewhat counter-intuitively, this is not where you can add members; this is done in the `Teams` tab (see [Teams](#teams) above). However, you can remove members from the `People` tab.
Somewhat counter-intuitively, this is not where you can add members;
this is done in the `Teams` tab (see [Teams](#teams) above).
However, you can remove members from the `People` tab.
The visibility of the members can also be edited here; `Hidden` means that the members' memberships will not be shown on their profiles, while `Visible` makes the avatar of the organization appear in the info card on their profile, as shown in the screenshot below. Note that your membership will always be visible to you on your profile; this visibility setting is for other users only.
The visibility of the members can also be edited here; `Hidden` means that the members' memberships will not be shown on
their profiles, while `Visible` makes the avatar of the organization appear in the info card on their profile,
as shown in the screenshot below. Note that your membership will always be visible to you on your profile;
this visibility setting is for other users only.
<img src="/images/collaborating/create-organization/profile.png" alt="profile">
@ -111,11 +139,16 @@ Finally, from here you can choose to leave the organization.
An overview of the repository permissions is given in the article [Repository Permissions](/collaborating/repo-permissions).
Members of the "Owners" team can do everything that admins can do. However, only owners of the organization can manage the organization, which includes:
Members of the "Owners" team can do everything that admins can do. However, only owners of the organization can manage
the organization, which includes:
- edit/delete the organization,
- add/remove members and teams,
- define access rights of teams,
- edit organization repository settings in the danger zone (i.e. transfer ownership, delete wiki data and repository, and archive repository).
- edit organization repository settings in the danger zone (i.e. transfer ownership, delete wiki data and repository,
and archive repository).
When owners allow members of a team to be able to create new repositories for the organization (see box "Create repositories" in [Teams](#teams) settings), the member who creates the repository will be added as a collaborator with administrator rights to this repository (see [Invite Collaborators](/collaborating/invite-collaborators) for details).
When owners allow members of a team to be able to create new repositories for the organization
(see box "Create repositories" in [Teams](#teams) settings), the member who creates the repository will be added as a
collaborator with administrator rights to this repository (see [Invite Collaborators](/collaborating/invite-collaborators)
for details).

17
content/collaborating/invite-collaborators.md
View file

@ -8,10 +8,17 @@ eleventyNavigation:
## Why invite collaborators?
If your project repository is public (see [Your First Repository](/getting-started/first-repository) on how to set up the visibility of a repository), everyone can see your repository, and every Codeberg user can contribute through issues and pull requests. This is contributing, but not collaborating, since you're still the only one who can _directly_ commit changes to your repository.
On the other hand, if your repository is private, only you, your collaborators and the members of your organization (depending on their permissions, see [Create and Manage an Organization](/collaborating/create-organization)) can access your repository. In other words, if you want Codeberg users outside of your organization to be able to work with you on your project, you have to grant them access to your repository by adding them as _collaborators_.
If your project repository is public (see [Your First Repository](/getting-started/first-repository) on how to set up the
visibility of a repository), everyone can see your repository, and every Codeberg user can contribute through issues and
pull requests. This is contributing, but not collaborating, since you're still the only one who can _directly_ commit
changes to your repository.
On the other hand, if your repository is private, only you, your collaborators and the members of your organization
(depending on their permissions, see [Create and Manage an Organization](/collaborating/create-organization)) can access
your repository. In other words, if you want Codeberg users outside of your organization to be able to work with you on
your project, you have to grant them access to your repository by adding them as _collaborators_.
It is important to understand that only registered Codeberg users can contribute. If you want a colleague or friend to work with you, you first have to make sure they have a Codeberg account (see [Your First Steps on Codeberg](/getting-started/first-steps)).
It is important to understand that only registered Codeberg users can contribute. If you want a colleague or friend
to work with you, you first have to make sure they have a Codeberg account (see [Your First Steps on Codeberg](/getting-started/first-steps)).
## Add a collaborator
@ -23,6 +30,8 @@ Then navigate to the `Collaborators` tab and search for the user you want to add
<img src="/images/collaborating/invite-collaborators/add-collaborator.png" alt="add-collaborator">
Once added, you can define the access rights by clicking on the shield: `Read`, `Write` or `Administrator` (see [Repository Permissions](/collaborating/repo-permissions) for details). This is also where you can remove collaborators.
Once added, you can define the access rights by clicking on the shield: `Read`, `Write` or `Administrator`
(see [Repository Permissions](/collaborating/repo-permissions) for details).
This is also where you can remove collaborators.
<img src="/images/collaborating/invite-collaborators/collaborator-rights.png" alt="collaborator-rights">

28
content/collaborating/pull-requests-and-git-flow.md
View file

@ -8,12 +8,16 @@ eleventyNavigation:
## Benefits of a pull-request based workflow
> **_TLDR:_** _Keep an eye on your repository and organization permissions. Don't take sweets from strangers. Use pull requests. Easy to review, easy to manage, and only the project maintainers/owners have permission to merge them._
> **_TLDR:_** _Keep an eye on your repository and organization permissions. Don't take sweets from strangers.
> Use pull requests. Easy to review, easy to manage, and only the project maintainers/owners have permission to merge them._
Although it is perfectly possible to use a Git project on Codeberg just as single shared central repository for individuals and teams, a collaborative workflow based on pull requests provides many benefits:
Although it is perfectly possible to use a Git project on Codeberg just as single shared central repository for
individuals and teams, a collaborative workflow based on pull requests provides many benefits:
- The "hot" project repository requires only very few maintainers with full rights to sign off pull requests. Contributors can easily work on forked repositories.
- Each pull request collects the full edit history for a fix or feature branch. Contributors can squash this, or keep it, just as they prefer.
- The "hot" project repository requires only very few maintainers with full rights to sign off pull requests.
Contributors can easily work on forked repositories.
- Each pull request collects the full edit history for a fix or feature branch.
Contributors can squash this, or keep it, just as they prefer.
### Cheat sheet
@ -23,7 +27,8 @@ First, fork the project you would like to work on, by clicking the `Fork` button
![Fork a project](/images/collaborating/pull-requests-and-git-flow/fork-button.png)
Then, clone it onto your local machine. We assume that [you have set up your SSH keys](/security/ssh-key). This has to be done only once:
Then, clone it onto your local machine. We assume that [you have set up your SSH keys](/security/ssh-key).
This has to be done only once:
```shell
git clone git@codeberg.org:<YOURCODEBERGUSERNAME>/examples.git
@ -51,9 +56,11 @@ Now you can create a pull request by selecting your feature branch, and clicking
### Keep it up-to-date: rebase pull requests to upstream
Sometimes the upstream project repository is evolving while we are working on a feature branch, and we need to rebase and resolve merge conflicts for upstream changes into our feature branch. This is not hard:
Sometimes the upstream project repository is evolving while we are working on a feature branch, and we need to rebase
and resolve merge conflicts for upstream changes into our feature branch. This is not hard:
In order to track the `upstream` repository, we'll add a second remote that is pointing to the original project. This has to be done only once:
In order to track the `upstream` repository, we'll add a second remote that is pointing to the original project.
This has to be done only once:
```shell
git remote add upstream git@codeberg.org:knut/examples.git
@ -62,7 +69,8 @@ git remote add upstream git@codeberg.org:knut/examples.git
You can also use the SSH variant here for public projects, if you want to be
able to pull without specifying your credentials.
Now, let's pull from `upstream`, and rebase our local branch against the latest `HEAD` of the upstream project repository (e.g. the `main` branch):
Now, let's pull from `upstream`, and rebase our local branch against the latest `HEAD` of the upstream project repository
(e.g. the `main` branch):
```shell
git pull --rebase upstream main
@ -73,8 +81,8 @@ That's it. You can now push your changes, and create the pull request as usual b
## A friendly note on owner rights, and force push permissions
Please keep in mind that project owners can do _everything_, including editing and rewriting the history using `force-push`. In some cases, this is a useful feature
(for example to undo accidental commits or clean up PRs),
Please keep in mind that project owners can do _everything_, including editing and rewriting the history using `force-push`.
In some cases, this is a useful feature (for example to undo accidental commits or clean up PRs),
but in most cases a transparent history based on a pull-request based workflow is surely preferable,
especially for the default branches of your project where other people rely on intact history.

36
content/collaborating/repo-permissions.md
View file

@ -6,21 +6,32 @@ eleventyNavigation:
order: 50
---
When you invite collaborators to join your repository (see [Invite Collaborators](/collaborating/invite-collaborators)) or when you create teams for your organization (see [Create and Manage an Organization](/collaborating/create-organization)), you have to decide what each collaborator/team is allowed to do.
When you invite collaborators to join your repository (see [Invite Collaborators](/collaborating/invite-collaborators))
or when you create teams for your organization (see [Create and Manage an Organization](/collaborating/create-organization)),
you have to decide what each collaborator/team is allowed to do.
You can assign teams different levels of permission for each unit (e.g. issues, PRs, wiki).
## Profile and Visibility
The visibility of your repositories will depend on the visibility of your profile, as well as whether you have marked a repository as private. Let's break down what this means:
The visibility of your repositories will depend on the visibility of your profile, as well as whether you have marked a
repository as private. Let's break down what this means:
- If your profile's visibility is set to "Limited", _all_ of your non-private repositories will only be visible to logged in users.
- If your profile's visibility is set to "Limited", _all_ of your non-private repositories will only be visible to logged
in users.
- If your profile's visibility is set to "Public", _all_ of your non-private repositories will be shown to everyone.
- If you do not want anyone (apart from [your fellow collaborators](https://docs.codeberg.org/collaborating/invite-collaborators/)) to see your repositories, mark your repository as "Private".
- If you do not want anyone (apart from [your fellow collaborators](https://docs.codeberg.org/collaborating/invite-collaborators/))
to see your repositories, mark your repository as "Private".
The visibility of your profile can be changed in the [Privacy settings](https://codeberg.org/user/settings). Be careful when you set your profile's visibility to "Limited"; Even if a repository is public, users that are _not logged in_ will get a [404 error](https://en.wikipedia.org/wiki/HTTP_404) if they try to access your repository — it will seem as if it does not exist at all!
The visibility of your profile can be changed in the [Privacy settings](https://codeberg.org/user/settings).
Be careful when you set your profile's visibility to "Limited"; Even if a repository is public, users that are
_not logged in_ will get a [404 error](https://en.wikipedia.org/wiki/HTTP_404) if they try to access your repository —
it will seem as if it does not exist at all!
<img src="/images/collaborating/repo-permissions/user-settings-privacy-limited.jpg" alt="Privacy Settings in Codeberg's User Settings" width="50%">
<img
src="/images/collaborating/repo-permissions/user-settings-privacy-limited.jpg"
alt="Privacy Settings in Codeberg's User Settings"
width="50%">
## Collaborators
@ -111,7 +122,9 @@ The table below gives an overview of what collaborators are allowed to do when g
<td> <span style="color: green">{% fas_icon "check" %}</span> </td>
</tr>
<tr>
<td> Configure repository settings in the danger zone (transfer ownership, delete wiki data / repository, archive repository) </td>
<td>
Configure repository settings in the danger zone (transfer ownership, delete wiki data / repository, archive repository)
</td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
<td> <span style="color: red">{% fas_icon "times" %}</span> </td>
@ -122,7 +135,8 @@ The table below gives an overview of what collaborators are allowed to do when g
## Teams
The permissions for teams are quite configurable. You can specify which repositories a team has access to; therefore, you can specify for each unit (Code Access, Issues, Releases) a different permission level.
The permissions for teams are quite configurable. You can specify which repositories a team has access to; therefore,
you can specify for each unit (Code Access, Issues, Releases) a different permission level.
Each unit is configured to have one of these 3 permission levels:
@ -130,7 +144,8 @@ Each unit is configured to have one of these 3 permission levels:
- Read: Members can view the unit, and do standard actions for that unit (See the Read column under [Collaborators](#collaborators)).
- Write: Members can view the unit, and execute write actions that unit (See the Write column under [Collaborators](#collaborators)).
When a team is configured to have administrator access, when this is specified, you cannot change units. The team will have admin permissions (See the Admin column under [Collaborators](#collaborators)).
When a team is configured to have administrator access, when this is specified, you cannot change units.
The team will have admin permissions (See the Admin column under [Collaborators](#collaborators)).
Currently, there are six units that can be configured:
@ -146,4 +161,5 @@ There are also two units which can be toggled:
- External Wiki: access to external wiki.
- External Issues: access to the external issue tracker.
A team can be given the permission to create new repositories. When a member of such team creates a new repository, they will get administrator access to the repository.
A team can be given the permission to create new repositories. When a member of such team creates a new repository,
they will get administrator access to the repository.

48
content/collaborating/resolve-conflicts.md
View file

@ -6,18 +6,21 @@ eleventyNavigation:
order: 60
---
When collaborating with others on a big project, sometimes it occurs that someone's change conflicts with another change introduced in the meantime (e.g by another person).
When collaborating with others on a big project, sometimes it occurs that someone's change conflicts with another change
introduced in the meantime (e.g by another person).
First of all: Do not panic! You should be able to resolve merge conflicts with a little time and patience.
While it is a good idea to rebase your branch before creating a pull request, as described in the article on [Pull requests and Git flow](/collaborating/pull-requests-and-git-flow),
While it is a good idea to rebase your branch before creating a pull request, as described in the article on
[Pull requests and Git flow](/collaborating/pull-requests-and-git-flow),
sometimes merge conflicts are unavoidable.
This article will explain what to do in case of a merge conflict, and how to resolve it using the command line.
Unfortunately, Forgejo currently does not provide a GUI to resolve conflicts.
An issue in the Gitea upstream repository of Forgejo, [#9014](https://github.com/go-gitea/gitea/issues/9014), requests this feature.
An issue in the Gitea upstream repository of Forgejo, [#9014](https://github.com/go-gitea/gitea/issues/9014),
requests this feature.
If you want to skip the setup of the examples, you can skip to the sections explaining the resolutions:
@ -108,7 +111,8 @@ git branch
Now, we want to merge both of the branches into the `main` branch.
First, we merge the branch named `add-link-to-readme`. As this is a simple change to a yet unchanged `main`-branch, there is no conflict.
First, we merge the branch named `add-link-to-readme`. As this is a simple change to a yet unchanged `main`-branch,
there is no conflict.
```shell
git switch main
@ -169,7 +173,8 @@ You have to resolve this conflict manually, as Git doesn't know how the resultin
### Resolving the conflict
Use your favorite text editor to open the file. The editor will show you the conflict. Git actually added the conflict description into the `README.md` file.
Use your favorite text editor to open the file. The editor will show you the conflict.
Git actually added the conflict description into the `README.md` file.
The end of the file now looks like this:
@ -182,7 +187,8 @@ An example repository to use with the Codeberg Documentation.
```
The conflict description starts with `<<<<<<< HEAD`.
The next line shows you that the current `HEAD` (the last commit on the `main` branch before we ran `git merge update-last-sentence-in-readme`) was:
The next line shows you that the current `HEAD` (the last commit on the `main` branch before
we ran `git merge update-last-sentence-in-readme`) was:
```
An example repository for [Codeberg Docs](https://docs.codeberg.org).
@ -194,9 +200,11 @@ The next line, `=======` separates the current line from the line proposed in th
An example repository to use with the Codeberg Documentation.
```
The last line `>>>>>>> update-last-sentence-in-readme` concludes the conflict description and tells you that the line(s) before are taken from the branch `update-last-sentence-in-readme`.
The last line `>>>>>>> update-last-sentence-in-readme` concludes the conflict description and tells you that the line(s)
before are taken from the branch `update-last-sentence-in-readme`.
Use your editor of choice, and change the line to reflect the changes you wish to commit to the repository after the resolution of the conflict.
Use your editor of choice, and change the line to reflect the changes you wish to commit to the repository after the
resolution of the conflict.
Remove all other lines, then the file should be in the form that you want to commit to the main branch.
@ -225,7 +233,8 @@ You can now mark the conflict as resolved, by calling `git add README.md`.
If you have more than one conflict in one or more files, repeat the resolution process until all conflicts are resolved.
Make sure not to leave any lines starting with `<<<<<<<`, `=======`, and `>>>>>>>`, as Git no longer knows that these are special and will treat them as normal text.
Make sure not to leave any lines starting with `<<<<<<<`, `=======`, and `>>>>>>>`, as Git no longer knows that these
are special and will treat them as normal text.
Issuing `git commit` without any comment will open the default editor, and lets you edit a commit message for the merge commit.
Closing the editor will complete the resolution of the merge conflict.
@ -262,14 +271,16 @@ Note the line starting with `Merge`; it includes the commit IDs of the two merge
Let's create another conflict.
We'll start again at the `main` branch. If you didn't work through the example above, you can jumpstart the environment for this example with these commands:
We'll start again at the `main` branch. If you didn't work through the example above, you can jumpstart the environment
for this example with these commands:
```shell
git clone git@codeberg.org:knut/examples.git
cd examples
```
If you're still on another branch from the last example, make sure that you start this example on the `main` branch, by running `git switch main`.
If you're still on another branch from the last example, make sure that you start this example on the `main` branch,
by running `git switch main`.
### Removing a file
@ -313,7 +324,8 @@ Again, switch back to the main branch.
git switch main
```
Merging the first branch does not lead to a conflict, because the `main` branch didn't change since the branch `remove-README-file` was created.
Merging the first branch does not lead to a conflict, because the `main` branch didn't change since the branch
`remove-README-file` was created.
```shell
git merge remove-README-file
@ -321,7 +333,8 @@ git merge remove-README-file
### Conflict and resolution
When we try to merge the second branch `adapt-README-file`, we get a conflict because the file we are trying to change, `README.md` was removed by our previous merge.
When we try to merge the second branch `adapt-README-file`, we get a conflict because the file we are trying to change,
`README.md` was removed by our previous merge.
```shell
$ git merge adapt-README-file
@ -364,10 +377,13 @@ git add README.md
Use `git commit` if you've resolved all conflicts (in this case it was only one).
As with before, issuing `git commit` without any comment will open your default editor, and ask you to provide a commit message for the merge commit.
As with before, issuing `git commit` without any comment will open your default editor, and ask you to provide a commit
message for the merge commit.
## Tips
- Try to avoid using `git push -f` on the target branch.
- Ensure that all branches are pushed to a remote repository before trying to resolve a conflict, as it makes it easier to start over in case you run into a problem.
- Search for `<<<<<<<`, `=======` and `>>>>>>>` in the resolved files, in order to not leave a conflict description in your files.
- Ensure that all branches are pushed to a remote repository before trying to resolve a conflict, as it makes it easier
to start over in case you run into a problem.
- Search for `<<<<<<<`, `=======` and `>>>>>>>` in the resolved files, in order to not leave a conflict description in
your files.

3
content/contact.md
View file

@ -33,7 +33,8 @@ There is a large and active community of users in our Matrix chats, which can al
### IRC
You can also join an unofficial (community-maintained) `#codeberg` IRC channel on [libera.chat](https://libera.chat). There's much less activity than on Matrix.
You can also join an unofficial (community-maintained) `#codeberg` IRC channel on [libera.chat](https://libera.chat).
There's much less activity than on Matrix.
## Contacting Codeberg e.V.

22
content/getting-started/email-settings.md
View file

@ -17,11 +17,14 @@ If you don't know how to **configure your name and email in Git**, take a look a
## Configuring all notifications
To change your notification preferences, go to your [Account Settings](https://codeberg.org/user/settings/account) or manually navigate to the settings page.
To change your notification preferences, go to your [Account Settings](https://codeberg.org/user/settings/account) or
manually navigate to the settings page.
You can access it by clicking on the menu button “Profile and Settings...” in the top-right corner of Codeberg. From this dropdown, click on Settings, then click on the Account tab.
You can access it by clicking on the menu button “Profile and Settings...” in the top-right corner of Codeberg.
From this dropdown, click on Settings, then click on the Account tab.
In the section “Manage Email Addresses”, you can select one of the following options from the drop-down menu for each email address that you have registered with Codeberg:
In the section “Manage Email Addresses”, you can select one of the following options from the drop-down menu for each
email address that you have registered with Codeberg:
| Option | Effect |
| :-------------------------- | :------------------------------------------------------------------------------------------------------ |
@ -39,14 +42,19 @@ Disabling email notifications doesn't mean that you'll stop receiving important
## Issue notifications
As soon as you make a comment on an issue, you automatically subscribe to it. Unless you disabled email notifications for all your email addresses, you will get an email for every change and comment on that issue.
As soon as you make a comment on an issue, you automatically subscribe to it. Unless you disabled email notifications
for all your email addresses, you will get an email for every change and comment on that issue.
You can check and modify your issue subscription status under the “Notifications” section on the menu on the right side of the issue screen.
You can check and modify your issue subscription status under the “Notifications” section on the menu on the right side
of the issue screen.
## Watching repositories
When you watch a repository (by clicking on the “Watch” button in a repository), you will receive emails for every change (creation of issues, pull requests, comments, etc.) done in this repository.
When you watch a repository (by clicking on the “Watch” button in a repository), you will receive emails for every change
(creation of issues, pull requests, comments, etc.) done in this repository.
To stop watching a repository, simply click on “Unwatch” in a repository.
To list all of your watched repositories, click [here](https://codeberg.org/notifications/watching). Alternatively you can click the menu button “Profile and Settings...” in the top-right corner of Codeberg and click on "Subscriptions" in the dropdown.
To list all of your watched repositories, click [here](https://codeberg.org/notifications/watching).
Alternatively you can click the menu button “Profile and Settings...” in the top-right corner of Codeberg and click on
"Subscriptions" in the dropdown.

12
content/getting-started/faq.md
View file

@ -61,7 +61,8 @@ Some other examples of free software works that we use are:
which is used internally by our non-profit association to carry out votes among members.
- [Even the text you are reading right now](https://codeberg.org/Codeberg/Documentation/src/branch/main/content/getting-started/faq.md)
is [licensed under a Creative Commons license](https://codeberg.org/Codeberg/Documentation/src/branch/main/LICENSE.md)!
- [Configuration and helper tools of Codeberg](https://codeberg.org/Codeberg-Infrastructure/) are also freely available for you to study, improve and reuse.
- [Configuration and helper tools of Codeberg](https://codeberg.org/Codeberg-Infrastructure/) are also freely available
for you to study, improve and reuse.
We use the [Codeberg organization](https://codeberg.org/Codeberg) (as well as other
organizations that are linked in its description) to share what we have worked on.
@ -71,9 +72,11 @@ More often than not, we also send patches to upstream projects; that way, we all
### Can I host software and resources without a free and open-source software license?
Our mission is to support the creation and development of Free Software; therefore we only allow repos licensed under an OSI/FSF-approved license.
Our mission is to support the creation and development of Free Software; therefore we only allow repos licensed under an
OSI/FSF-approved license.
For more details see [Licensing article](/getting-started/licensing).
However, we sometimes tolerate repositories that aren't perfectly licensed and focus on spreading awareness of the topic of improper FLOSS licensing and its issues.
However, we sometimes tolerate repositories that aren't perfectly licensed and focus on spreading awareness of the topic
of improper FLOSS licensing and its issues.
### Can I use private repositories for my project?
@ -83,7 +86,8 @@ However, if we see that you contribute to Free Software / Content and the ecosys
we allow **up to 100 MB of private content** for your convenience.
Further exceptions are spelled out in our [Terms of Service](https://codeberg.org/codeberg/org/src/TermsOfUse.md#2-allowed-content-usage):
> Private repositories are only allowed for things required for FLOSS projects, like storing secrets, team-internal discussions or hiding projects from the public until they're ready for usage and/or contribution.
> Private repositories are only allowed for things required for FLOSS projects, like storing secrets, team-internal
> discussions or hiding projects from the public until they're ready for usage and/or contribution.
If you are still not sure if your usage is allowed or if you require a lot of private space for a Free Software project,
[please send us a formal request](https://codeberg.org/Codeberg-e.V./requests) and we'll have a look.

135
content/getting-started/first-repository.md
View file

@ -6,15 +6,18 @@ eleventyNavigation:
order: 30
---
Almost everything on Codeberg happens in a repository. Think of a repository as a home for your project, where all of its source code can be organized using Git, as well as where you can track issues and read and write wikis.
Almost everything on Codeberg happens in a repository. Think of a repository as a home for your project, where all of its
source code can be organized using Git, as well as where you can track issues and read and write wikis.
This article will guide you through creating your first repository on Codeberg, connecting your local development environment and making your first commit.
This article will guide you through creating your first repository on Codeberg, connecting your local development
environment and making your first commit.
## Creating a Repository
{% admonition "warning" %}
Note for advanced users: The [Push To Create](https://forgejo.org/docs/latest/user/push-to-create/) feature is disabled on Codeberg.
Note for advanced users: The [Push To Create](https://forgejo.org/docs/latest/user/push-to-create/) feature is disabled
on Codeberg.
{% endadmonition %}
@ -30,17 +33,29 @@ This will lead you to this page below.
Here's an explanation of the form's fields:
- **Owner** Here, you can specify whether you want this to be your own personal project or whether you want it to be part of an organization that you're a part of
- **Owner** Here, you can specify whether you want this to be your own personal project or whether you want it to be part
of an organization that you're a part of
- **Repository name** A name for your repository (which will also be part of its path, in this case `https://codeberg.org/knut/foobar`)
- **Visibility** Repositories are either _public_ or _private_, where public means that everyone will be able to access your repository, while your private repositories can only be accessed by you and your collaborators (see [Invite Collaborators](/collaborating/invite-collaborators))
- **Visibility** Repositories are either _public_ or _private_, where public means that everyone will be able to access
your repository, while your private repositories can only be accessed by you and your collaborators (see [Invite Collaborators](/collaborating/invite-collaborators))
- **Description** A short description that appears next to your repository's name where appropriate
- **Template** Occasionally you may want to generate your repository from an existing template. In that case, you can specify that template here. Otherwise, simply leave this field empty.
- **Issue Labels** If you want to initialize your project's issue tracker with a set of labels that you can use to categorize issues, you can choose one here. You don't have to choose this right away though, as you can choose and modify issue labels at a later time as well.
- **.gitignore** A [.gitignore](https://git-scm.com/docs/gitignore) file defines which files Git should not keep track of. This is useful, for example to prevent configuration files or binaries to be tracked in version control. You can choose to add a pre-defined file matching the programming language you use now, or add one manually later.
- **License** Here, you can choose from a list of FSF/OSI approved licenses. A `LICENSE` file will then be added to the repository. For some help on choosing the correct license, have a look at our [licensing article](/getting-started/licensing).
- **README** is the first file one should read when accessing a repository. It's also the first file displayed when accessing a repository, a bit like the "homepage" of your repository. On Codeberg, this is interpreted as a [Markdown](/markdown) file.
- **Initialize repository** In order to add the `LICENSE`, `README` and `.gitignore` files mentioned above to your new repository, make sure you tick this box.
- **Default branch** Using this field, you can choose how to name the default branch of your Git repository. We recommend you use the predefined default.
- **Template** Occasionally you may want to generate your repository from an existing template.
In that case, you can specify that template here. Otherwise, simply leave this field empty.
- **Issue Labels** If you want to initialize your project's issue tracker with a set of labels that you can use to
categorize issues, you can choose one here.
You don't have to choose this right away though, as you can choose and modify issue labels at a later time as well.
- **.gitignore** A [.gitignore](https://git-scm.com/docs/gitignore) file defines which files Git should not keep track of.
This is useful, for example to prevent configuration files or binaries to be tracked in version control.
You can choose to add a pre-defined file matching the programming language you use now, or add one manually later.
- **License** Here, you can choose from a list of FSF/OSI approved licenses. A `LICENSE` file will then be added to the
repository. For some help on choosing the correct license, have a look at our [licensing article](/getting-started/licensing).
- **README** is the first file one should read when accessing a repository. It's also the first file displayed when
accessing a repository, a bit like the "homepage" of your repository. On Codeberg,
this is interpreted as a [Markdown](/markdown) file.
- **Initialize repository** In order to add the `LICENSE`, `README` and `.gitignore` files mentioned above to your new repository,
make sure you tick this box.
- **Default branch** Using this field, you can choose how to name the default branch of your Git repository.
We recommend you use the predefined default.
{% admonition "warning" %}
@ -50,7 +65,8 @@ To prevent this, ensure the option
[]-Initialize repository (Adds .gitignore, LICENSE and README)
is **not** checked.
If Codeberg creates files, you will end up with two repositories without any shared history and Codeberg will refuse to sync them until you resolve the 'conflicts' manually.
If Codeberg creates files, you will end up with two repositories without any shared history and Codeberg will refuse to
sync them until you resolve the 'conflicts' manually.
Instead, see Option B below.
{% endadmonition %}
@ -58,46 +74,60 @@ Instead, see Option B below.
It's okay to only specify owner and repository name, if you want to get started quickly.
After filling out the fields, click the green "Create Repository" button on the bottom of the page.
You should now see a screen similar to the one below. If you haven't chosen to generate `LICENSE`, `README` and `.gitignore` the screen might show instructions instead, which will vanish after [your first commit](#making-your-first-commit).
You should now see a screen similar to the one below. If you haven't chosen to generate `LICENSE`, `README` and `.gitignore`
the screen might show instructions instead, which will vanish after [your first commit](#making-your-first-commit).
<img src="/images/getting-started/first-repository/create-repo-3.png" alt="Repository Main View">
Here's what the most important buttons here do:
- **Repository Settings (1)** is where you can make adjustments to your repository settings, such as setting a project website, changing the repository description, enabling/disabling a wiki and issue tracker or deleting the repository. You may want to give this page a visit right now, to get an overview of your options.
- **The Watch, Star and Fork buttons (2)** allow you to interact with others' repositories. While they don't do much for your own repository, when visiting another user's repository, you can click on "Watch" to get notified about everything important happening in that repository, "Star" to show the user your appreciation (and to help other users find interesting projects more quickly) and "Fork" to create your own copy of the repository, for example to make modifications that you want to share with the original author.
- **Repository Settings (1)** is where you can make adjustments to your repository settings, such as setting a project
website, changing the repository description, enabling/disabling a wiki and issue tracker or deleting the repository.
You may want to give this page a visit right now, to get an overview of your options.
- **The Watch, Star and Fork buttons (2)** allow you to interact with others' repositories.
While they don't do much for your own repository, when visiting another user's repository, you can click on "Watch" to
get notified about everything important happening in that repository, "Star" to show the user your appreciation
(and to help other users find interesting projects more quickly) and "Fork" to create your own copy of the repository,
for example to make modifications that you want to share with the original author.
- **The Repository Tabs (3)** contain links to every important feature within your repository:
- **Code** lets you browse through all versions of your code
- **Issues** is a very important communication tool between you, your users and your contributors. Think of it as part bug-tracker, part forum.
- **Issues** is a very important communication tool between you, your users and your contributors.
Think of it as part bug-tracker, part forum.
For more information on this, have a look at [The Basics of Issue Tracking](/getting-started/issue-tracking-basics)
- **Pull Requests** is where other users can ask you to "pull" in code, from a fork into your program
- **Releases** is a space where you can upload finished versions of your program, e.g. binaries
- **Wiki** is a basic wiki feature built into Forgejo, the software Codeberg is based on
- **Activity** calculates statistics about your repository
- **Your repository's Git URLs (4)** - use these to let Git know where to find your repository. Don't worry if you don't understand this now - we will look at this in the following section.
- **Your repository's Git URLs (4)** - use these to let Git know where to find your repository.
Don't worry if you don't understand this now - we will look at this in the following section.
## Connect a local repository to Codeberg
After creating a new repository, as laid out in the previous section, you can now move on to connect the repository with your local development copy.
After creating a new repository, as laid out in the previous section, you can now move on to connect the repository with
your local development copy.
In this guide, we'll focus on connecting to Codeberg via HTTP using Git on the command line, but note that there are multiple other ways to connect to Codeberg, as laid out in more detail in the articles:
In this guide, we'll focus on connecting to Codeberg via HTTP using Git on the command line, but note that there are
multiple other ways to connect to Codeberg, as laid out in more detail in the articles:
- [Clone & Commit via CLI](/git/clone-commit-via-cli/) and
- [Clone & Commit via Web](/git/clone-commit-via-web)
{% admonition "tip" %}
Although we use HTTP in this Getting Started guide, it is a good idea to [setup SSH-based authentication](/security/ssh-key) once you feel confident to do so.
Although we use HTTP in this Getting Started guide, it is a good idea to [setup SSH-based authentication](/security/ssh-key)
once you feel confident to do so.
{% endadmonition %}
### Option A: Clone the newly created, empty repository
If you want to start a fresh project (so if you don't already have source code that you want to upload to Codeberg), the quickest way to get started is to clone your newly created repository like this:
If you want to start a fresh project (so if you don't already have source code that you want to upload to Codeberg),
the quickest way to get started is to clone your newly created repository like this:
#### 1. Navigate to your local workspace (optional)
If you're just getting started, it's a good idea to keep your projects neatly sorted in a dedicated directory, like in this example:
If you're just getting started, it's a good idea to keep your projects neatly sorted in a dedicated directory,
like in this example:
```bash
knut@iceberg:~$ mkdir repositories
@ -123,7 +153,8 @@ Unpacking objects: 100% (4/4), 11.94 KiB | 764.00 KiB/s, done.
#### 3. Navigate to the cloned repository
After cloning, the repository should now be in a new directory with the same name as your repository. In this case, it's called `foobar`.
After cloning, the repository should now be in a new directory with the same name as your repository.
In this case, it's called `foobar`.
```bash
knut@iceberg:~/repositories$ cd foobar
@ -161,7 +192,8 @@ git add already-written.tex
#### 4. First commit
For Option B, your first commit **must** be local to avoid conflicts. This is why we prevented Codeberg from adding any files above.
For Option B, your first commit **must** be local to avoid conflicts. This is why we prevented Codeberg from adding any
files above.
```bash
git commit -m "first commit"
@ -173,7 +205,8 @@ Now, you need to tell Git where to push your changes. You would do that by speci
{% admonition "tip" %}
In this example, we'll specify Codeberg as the `origin` remote. You can name your remote any other way, especially if you already have an `origin`, but `origin` is the recommended name for the main remote repository.
In this example, we'll specify Codeberg as the `origin` remote. You can name your remote any other way, especially if
you already have an `origin`, but `origin` is the recommended name for the main remote repository.
{% endadmonition %}
@ -183,7 +216,8 @@ knut@iceberg:~/my-project$ git remote add origin https://codeberg.org/knut/fooba
{% admonition "info" %}
When you clone a repository from the Internet, the URL that you got your copy of the repository from will be automatically used for the `origin` remote.
When you clone a repository from the Internet, the URL that you got your copy of the repository from will be
automatically used for the `origin` remote.
{% endadmonition %}
@ -193,11 +227,13 @@ When you clone a repository from the Internet, the URL that you got your copy of
git push -u origin main
```
Now your Codeberg repository shares a common history with your local repository, you can make changes to either and use `git` to manage them.
Now your Codeberg repository shares a common history with your local repository, you can make changes to either and use
`git` to manage them.
#### 7. Add standard files
Codeberg does not provide an interface to add licence files, `.gitignore` or `README.md` retrospectively, so you should add at least the licence and `README.md` yourself.
Codeberg does not provide an interface to add licence files, `.gitignore` or `README.md` retrospectively,
so you should add at least the licence and `README.md` yourself.
- To choose a licence, read [Codeberg's guidance](https://docs.codeberg.org/getting-started/licensing/).
- If you already know which licence you need, Codeberg has [copies](https://codeberg.org/Codeberg-Infrastructure/forgejo/src/branch/codeberg-9/options/license).
@ -207,13 +243,15 @@ Codeberg does not provide an interface to add licence files, `.gitignore` or `RE
Now that you've connected your repository to your local development copy, it's time to make your first commit.
> If you didn't generate the `LICENSE` and `README.md` files when creating the repository, it's a good idea to add them now. Just put them in your local development copy's directory and add them to your commit, as shown below.
> If you didn't generate the `LICENSE` and `README.md` files when creating the repository, it's a good idea to add them now.
> Just put them in your local development copy's directory and add them to your commit, as shown below.
#### 1. Create or edit a file
Let's modify the `README.md` file.
> If you didn't generate `README.md`, these commands will still work fine. However, instead of "Hello World!" being at the end of the file, it'll be the only line in the file.
> If you didn't generate `README.md`, these commands will still work fine. However, instead of "Hello World!" being at
> the end of the file, it'll be the only line in the file.
```bash
knut@iceberg:~/repositories/foobar$ echo "Hello World!" >> README.md
@ -250,15 +288,20 @@ knut@iceberg:~/repositories/foobar$ git add README.md
This command should output nothing.
> If you want to add all modified files in your source tree, you can run `git add .` but **be careful** as this might add unwanted files as well, so it's a good idea to double-check by running `git status` before committing.
> If you want to add all modified files in your source tree, you can run `git add .` but **be careful** as this might add
> unwanted files as well, so it's a good idea to double-check by running `git status` before committing.
#### 3. Commit your changes
By committing your changes, you create a new step in the version history of your program. They act like snapshots of your program's state at a given point of time, and you will later be able to jump back and forth between them.
By committing your changes, you create a new step in the version history of your program.
They act like snapshots of your program's state at a given point of time, and you will later be able to jump back and
forth between them.
> It is recommended to keep commits small and focused, so that, if necessary, they can be reverted or easily adapted into another context without too many side-effects.
> It is recommended to keep commits small and focused, so that, if necessary, they can be reverted or easily adapted into
> another context without too many side-effects.
To commit your changes, run `git commit` and specify a commit message; this will later help you (and others) to identify that commit when looking back at your version history.
To commit your changes, run `git commit` and specify a commit message; this will later help you (and others) to identify
that commit when looking back at your version history.
```bash
knut@iceberg:~/repositories/foobar$ git commit -m "My first commit on Codeberg"
@ -306,17 +349,21 @@ Branch 'main' set up to track remote branch 'main' from 'origin'.
{% admonition "warning" %}
If your local copy of the repository is missing some commits that exist in the remote repository, pushing will result in an error. There are two ways to fix this:
If your local copy of the repository is missing some commits that exist in the remote repository, pushing will result in
an error. There are two ways to fix this:
- Run `git pull` to combine your local changes with the changes that exist in the remote repository. If this does not work, please follow the instructions in your terminal.
- Run `git pull` to combine your local changes with the changes that exist in the remote repository.
If this does not work, please follow the instructions in your terminal.
- If you know what you are doing, you can also overwrite the remote repository using `git -f push`.
This action will **permanently** alter your remote repository and is not suitable if you are working on a project together with other people.
This action will **permanently** alter your remote repository and is not suitable if you are working on a project
together with other people.
{% endadmonition %}
The `-u` option sets the upstream remote, which we want to be Codeberg.org, as configured previously.
The `main` argument sets the name of the branch onto which shall be pushed upstream. For this example, it should be the same branch name that you specified when creating the repository.
The `main` argument sets the name of the branch onto which shall be pushed upstream.
For this example, it should be the same branch name that you specified when creating the repository.
When connecting via HTTPS, Git will ask you for your username and password, which you can enter interactively.
@ -328,7 +375,8 @@ Congratulations - you've just made your first source code contribution on Codebe
### Promote your work
If you want to promote your work you can use [Codeberg's Badge Generator](https://get-it-on.codeberg.org/) to easily generate a badge which links to you repository.
If you want to promote your work you can use [Codeberg's Badge Generator](https://get-it-on.codeberg.org/) to easily
generate a badge which links to you repository.
In the badge generator you can edit how the badge should appear. Mainly this is:
@ -357,7 +405,12 @@ or in HTML:
This will result in a badge like this:
<a href="https://codeberg.org/Codeberg/Documentation">
<img src="https://codeberg.org/Codeberg/GetItOnCodeberg/raw/branch/main/get-it-on-blue-on-white.svg" alt="Get It On Codeberg" style="border:0px" width="250">
<img
src="https://codeberg.org/Codeberg/GetItOnCodeberg/raw/branch/main/get-it-on-blue-on-white.svg"
alt="Get It On Codeberg"
style="border:0px"
width="250"
>
</a>
Now, you should [learn more about issue tracking](/getting-started/issue-tracking-basics).

26
content/getting-started/first-steps.md
View file

@ -18,13 +18,17 @@ you're done and good to go!
## Community
Codeberg is a non-profit volunteer effort. It relies on its friendly and dedicated community. We're happy that you're now a part of our community, too, and we hope you're feeling welcome!
Codeberg is a non-profit volunteer effort. It relies on its friendly and dedicated community.
We're happy that you're now a part of our community, too, and we hope you're feeling welcome!
We kindly ask you to be polite and civil when on Codeberg and to not excessively use the resources provided. Please see our [Terms of Use](https://codeberg.org/codeberg/org/src/TermsOfUse.md) for details.
We kindly ask you to be polite and civil when on Codeberg and to not excessively use the resources provided.
Please see our [Terms of Use](https://codeberg.org/codeberg/org/src/TermsOfUse.md) for details.
Please remember that everyone here is contributing on their free time, as volunteers.
If you like a project on Codeberg, consider **giving it a star** and/or **following its author**. This helps with building and growing a network of free software projects and people, and can serve as guidance for users exploring Codeberg, looking for interesting projects to try out or contribute to.
If you like a project on Codeberg, consider **giving it a star** and/or **following its author**.
This helps with building and growing a network of free software projects and people, and can serve as guidance for users
exploring Codeberg, looking for interesting projects to try out or contribute to.
## Orienting yourself on Codeberg
@ -36,11 +40,17 @@ An explanation of the highlighted elements above:
- **Dashboard (1)** is the screen you're looking at right now. It gives you an overview of the latest activity
from you, the people you follow and in your or your organization's projects.
- **Issues (2)** and **Pull Requests (3)** These are overviews of issues and pull requests that you are either involved in or that are part of one of the organizations you belong to.
- **Codeberg Issues (4)** This is currently the primary communication channel for the Codeberg Community. Here, you can ask questions, report bugs and suggest changes to Codeberg. You're also welcome to browse these issues and contribute your solutions, if you want to support Codeberg even more.
- **The Create Menu (5)** You can create repositories, organizations and migrate repositories using this menu. It's your entry point to kicking off entirely new projects on Codeberg.
- **Your Avatar (6)** will lead you to a menu, where you can look at your profile, edit your settings, read the documentation of Forgejo (the software Codeberg is based on) or log out.
- **The Dashboard Context Switcher (7)** If you're part of one or more organizations, you can use this context switcher to let the dashboard display information relevant to the organization, rather than your account.
- **Issues (2)** and **Pull Requests (3)** These are overviews of issues and pull requests that you are either involved
in or that are part of one of the organizations you belong to.
- **Codeberg Issues (4)** This is currently the primary communication channel for the Codeberg Community.
Here, you can ask questions, report bugs and suggest changes to Codeberg. You're also welcome to browse these issues
and contribute your solutions, if you want to support Codeberg even more.
- **The Create Menu (5)** You can create repositories, organizations and migrate repositories using this menu.
It's your entry point to kicking off entirely new projects on Codeberg.
- **Your Avatar (6)** will lead you to a menu, where you can look at your profile, edit your settings,
read the documentation of Forgejo (the software Codeberg is based on) or log out.
- **The Dashboard Context Switcher (7)** If you're part of one or more organizations, you can use this context switcher
to let the dashboard display information relevant to the organization, rather than your account.
## A word about Security

11
content/getting-started/index.md
View file

@ -7,15 +7,20 @@ eleventyNavigation:
description: This article shows you how to get started with Codeberg
---
<img src="/images/getting-started/knut.svg" style="float: right; width: 150px; border: none; margin-left: 25px; margin-bottom: 25px;" alt="Knut the Polar Bear">
<img
src="/images/getting-started/knut.svg"
style="float: right; width: 150px; border: none; margin-left: 25px; margin-bottom: 25px;"
alt="Knut the Polar Bear">
Hello there!
We're glad you're considering to join Codeberg, the <span style="white-space: nowrap;">community-driven</span> <span style="white-space: nowrap;">non-profit</span> software development platform.
We're glad you're considering to join Codeberg, the <span style="white-space: nowrap;">community-driven</span>
<span style="white-space: nowrap;">non-profit</span> software development platform.
I'm Knut the Polar Bear, and I'm going to guide you through your first steps on Codeberg.
You can start with [finding out more about Codeberg](/getting-started/what-is-codeberg) or by jumping right to [your first steps on Codeberg](/getting-started/first-steps).
You can start with [finding out more about Codeberg](/getting-started/what-is-codeberg) or by jumping right to
[your first steps on Codeberg](/getting-started/first-steps).
Welcome to Codeberg! 😊

62
content/getting-started/install-git.md
View file

@ -6,9 +6,12 @@ eleventyNavigation:
order: 25
---
Projects on Codeberg use [Git](https://git-scm.com/) as their [version control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) system. If you want to contribute source code, it's a good idea to install Git at this point.
Projects on Codeberg use [Git](https://git-scm.com/) as their
[version control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) system.
If you want to contribute source code, it's a good idea to install Git at this point.
Git runs on every OS. You can download it directly from the [Git website](https://git-scm.com/downloads), or from your operating system’s package manager (if available).
Git runs on every OS. You can download it directly from the [Git website](https://git-scm.com/downloads),
or from your operating system’s package manager (if available).
Here we provide step-by-step instructions to install it.
@ -16,13 +19,16 @@ Here we provide step-by-step instructions to install it.
## Linux
On Linux, you can install Git directly from your package manager. Check out [Git's official documentation](https://git-scm.com/download/linux) to get the right command for your distro.
On Linux, you can install Git directly from your package manager. Check out [Git's official documentation](https://git-scm.com/download/linux)
to get the right command for your distro.
Please see also the article [Configuring Git](/git/configuring-git), which describes how to set up your name and email address for Git.
Please see also the article [Configuring Git](/git/configuring-git), which describes how to set up your name and email
address for Git.
## macOS
There are [several ways](https://git-scm.com/download/mac) to install Git on macOS. This guide will show you how to install Git using the Homebrew package manager. You will need to be on macOS High Sierra (10.13) or higher.
There are [several ways](https://git-scm.com/download/mac) to install Git on macOS. This guide will show you how to
install Git using the Homebrew package manager. You will need to be on macOS High Sierra (10.13) or higher.
### Install
@ -44,7 +50,8 @@ To update Git, run the following command.
### Configure
Git is now up and running. Please proceed as described in the article [Configuring Git](/git/configuring-git) to set up your name and email address for Git.
Git is now up and running. Please proceed as described in the article [Configuring Git](/git/configuring-git) to set up
your name and email address for Git.
## Windows 10
@ -52,12 +59,15 @@ There are several ways to install Git on Windows. An easy one is to use Git’s
### Permissions
For some Git clients (see [below](#git-clients)), e.g. [RStudio](https://rstudio.com/), it is recommended to install Git as administrator. It is also possible to install Git as a standard user, but you may have to manually specify the path to the Git executable in the settings of your Git client.
For some Git clients (see [below](#git-clients)), e.g. [RStudio](https://rstudio.com/), it is recommended to install Git
as administrator. It is also possible to install Git as a standard user, but you may have to manually specify the path
to the Git executable in the settings of your Git client.
### Install
If you want to install Git as a standard user, just log in with your user account and run the installer.
To install with administrator permissions, run the installer as administrator. Right-click on the installer, select `Run as administrator` and enter your credentials:
To install with administrator permissions, run the installer as administrator. Right-click on the installer,
select `Run as administrator` and enter your credentials:
<img src="/images/getting-started/install-git/win-run-as-admin.png" alt="win-run-admin">
@ -67,32 +77,43 @@ Here are some important steps:
1. Choose your editor:<br>
By default, [Vim](https://www.vim.org/) will be used for Git. If you prefer to use another editor, select it here.
<img src="/images/getting-started/install-git/win-editor.png" alt="win-editor">
<img src="/images/getting-started/install-git/win-editor.png" alt="win-editor">
2. PATH environment:
This ensures that Git can be used by 3rd party software ([Git clients](#git-clients)). PATH adjustment is recommended (and the default).
This ensures that Git can be used by 3rd party software ([Git clients](#git-clients)).
PATH adjustment is recommended (and the default).
<img src="/images/getting-started/install-git/win-path.png" alt="win-path">
<img src="/images/getting-started/install-git/win-path.png" alt="win-path">
3. Choose credential helper:
From Git 2.29.0 onwards, the `Git Credential Manager Core` will be used by default. The `Git Credential Manager` can still be installed and used, but is now deprecated. When using either of these, your Git/Codeberg credentials will be stored in Windows' [Credential Manager](https://support.microsoft.com/en-us/help/4026814/windows-accessing-credential-manager) when you enter them for your first pull/push (see [Clone & Commit via HTTP](/git/clone-commit-via-http)). Windows' Credential Manager is also where you'd go to change them. Follow the links on the setup wizard for more details.
If you'd prefer not to store your credentials in Windows but e.g. in a password manager, select the third option (`None`). You'll have to enter your credentials at every push/pull.
From Git 2.29.0 onwards, the `Git Credential Manager Core` will be used by default.
The `Git Credential Manager` can still be installed and used, but is now deprecated.
When using either of these, your Git/Codeberg credentials will be stored in Windows' [Credential Manager](https://support.microsoft.com/en-us/help/4026814/windows-accessing-credential-manager)
when you enter them for your first pull/push (see [Clone & Commit via HTTP](/git/clone-commit-via-http)).
Windows' Credential Manager is also where you'd go to change them.
Follow the links on the setup wizard for more details.
If you'd prefer not to store your credentials in Windows but e.g. in a password manager, select the third option (`None`).
You'll have to enter your credentials at every push/pull.
<img src="/images/getting-started/install-git/win-cred-helper.png" alt="win-cred-helper">
> You may get the error message displayed below, saying that the release notes cannot be displayed. This can be safely ignored; you can find the release notes in `Start Menu → Git → Git Release Notes`.
> You may get the error message displayed below, saying that the release notes cannot be displayed.
> This can be safely ignored; you can find the release notes in `Start Menu → Git → Git Release Notes`.
>
> <img src="/images/getting-started/install-git/win-error-notes.png" alt="win-error">
### Run
Git can be used through `Command Prompt` (the traditional Windows command line interpreter), `PowerShell` (the "replacement" of Command Prompt), your [Git client](#git-clients), or `Git Bash`. The latter two options are recommended.
Git can be used through `Command Prompt` (the traditional Windows command line interpreter), `PowerShell`
(the "replacement" of Command Prompt), your [Git client](#git-clients), or `Git Bash`.
The latter two options are recommended.
`Git Bash` is what comes with Git. You can access it from the Start Menu: `Git → Git Bash`.
### Configure
You have now managed to get Git up and running. Please proceed as described in the article [Configuring Git](/git/configuring-git) to set up your name and email address for Git.
You have now managed to get Git up and running. Please proceed as described in the article [Configuring Git](/git/configuring-git)
to set up your name and email address for Git.
### Update
@ -107,11 +128,14 @@ After that, just follow the instructions in the terminal to update to the latest
Alternatively, you can download the installer from the Git website as explained above.
> Make sure that you run the new installer with the same permissions (Administrator or standard user) as the original installation. If not, it will be installed twice and that will create a mess.
> Make sure that you run the new installer with the same permissions (Administrator or standard user) as the original
> installation. If not, it will be installed twice and that will create a mess.
If you want to keep all your previous settings, simply tick the box `Only show new options` in the setup wizard (see screenshots above).
If you want to keep all your previous settings, simply tick the box `Only show new options` in the setup wizard
(see screenshots above).
## Git clients
Git can be used from the command line as shown above, but it can also be used through graphical user interfaces called _Git clients_.
Git can be used from the command line as shown above, but it can also be used through graphical user interfaces called
_Git clients_.
You can find a list of various Git clients on the [Git website](https://git-scm.com/downloads/guis).

3
content/getting-started/issue-tracking-basics.md
View file

@ -42,7 +42,8 @@ process of review, discussion and closure, which can be more or less strictly de
based on the project you're contributing to.
The first thing that might happen is that your issue is categorized using labels.
Your issue may be reviewed by the project's maintainer(s) and evaluated whether it, i.e., might be a duplicate or an invalid bug report.
Your issue may be reviewed by the project's maintainer(s) and evaluated whether it, i.e., might be a duplicate or an
invalid bug report.
Then, depending on what type of issue it is, there might be additional questions
or a discussion and, if applicable, the implementation of a solution (or the rejection of

174
content/getting-started/licensing.md
View file

@ -6,25 +6,41 @@ eleventyNavigation:
order: 70
---
Adding a license to a project is essential for making it reusable: In the absence of other agreements, in fact, copyright law would otherwise forbid others from (re-)using and distributing your work.
Moreover, a license can further specify other important properties, such as the temporary- or forever-openness of the code, the rights granted to the users (such as the [four fundamental software freedoms](https://www.gnu.org/philosophy/free-sw.html#four-freedoms)), or the permission of using patents encoded in a program.
Adding a license to a project is essential for making it reusable: In the absence of other agreements, in fact,
copyright law would otherwise forbid others from (re-)using and distributing your work.
Moreover, a license can further specify other important properties, such as the temporary- or forever-openness of the code,
the rights granted to the users (such as the [four fundamental software freedoms](https://www.gnu.org/philosophy/free-sw.html#four-freedoms)),
or the permission of using patents encoded in a program.
## Copyright: The mechanism behind most software licenses
The international validity of most common licenses is guaranteed by copyright law, and in particular by the [Copyright Treaty](https://en.wikipedia.org/wiki/WIPO_Copyright_Treaty) of the United Nations' (UN) World Intellectual Property Organization (WIPO) adopted in 1996. This treaty sets a common denominator for all adhering countries, but individual countries can still extend domestically the reach of copyright. The article 4 of the Copyright Treaty clarified once for all that computer programs are protected by copyright just as literary works. Unfortunately, however, copyright law does not protect hardware objects.
The international validity of most common licenses is guaranteed by copyright law, and in particular by the [Copyright Treaty](https://en.wikipedia.org/wiki/WIPO_Copyright_Treaty)
of the United Nations' (UN) World Intellectual Property Organization (WIPO) adopted in 1996.
This treaty sets a common denominator for all adhering countries, but individual countries can still extend domestically
the reach of copyright. The article 4 of the Copyright Treaty clarified once for all that computer programs are
protected by copyright just as literary works.
Unfortunately, however, copyright law does not protect hardware objects.
[Copyright law is extremely powerful](https://www.gnu.org/philosophy/enforcing-gpl.en.html). In fact, it grants the author of a work exclusive rights to use or distribute their work. An author can grant permission of using his/her work under arbitrary conditions; just for illustration, an author could invent for example a "coffee license" and impose that whoever uses his work has to offer the author a coffee. Similarly, forever-open licenses grant users the right to use the work provided that they will redistribute any derivative work using the same license again (copyleft).
[Copyright law is extremely powerful](https://www.gnu.org/philosophy/enforcing-gpl.en.html).
In fact, it grants the author of a work exclusive rights to use or distribute their work.
An author can grant permission of using his/her work under arbitrary conditions; just for illustration, an author could
invent for example a "coffee license" and impose that whoever uses his work has to offer the author a coffee.
Similarly, forever-open licenses grant users the right to use the work provided that they will redistribute any
derivative work using the same license again (copyleft).
## Simplified decision diagram for choosing a software license
If you start a new software project, the diagram below can help you quickly decide on which free software license to choose.
If you need a license for a [non-software project](#hardware-projects), you can skip this section. Later sections will explain the different choices in more details.
If you need a license for a [non-software project](#hardware-projects), you can skip this section.
Later sections will explain the different choices in more details.
### License decision diagram
Do you either want to allow people to create proprietary (closed-source) projects with your code, or do you expect your project to remain small (e.g. less than 300 lines)?
Do you either want to allow people to create proprietary (closed-source) projects with your code, or do you expect your
project to remain small (e.g. less than 300 lines)?
- No --> Do you want to allow people to create a closed-source service, for example by using your code on a web server without releasing the source code?
- No --> Do you want to allow people to create a closed-source service, for example by using your code on a web server
without releasing the source code?
- No --> We recommend using the **AGPL-3.0-or-later** license
- Yes --> Do you want to allow people to use your code as a library and not disclose the source-code of their main program?
- No --> we recommend using the **GPL-3.0-or-later** license
@ -35,10 +51,14 @@ Do you either want to allow people to create proprietary (closed-source) project
## Correctly applying a license
In order to correctly license your work, you have to explicitly tell which files of your work are under which license, and how to find the full license text.
In order to correctly license your work, you have to explicitly tell which files of your work are under which license,
and how to find the full license text.
We recommend to follow these steps to avoid ambiguities:
- Important: Make a clear statement about the license of the project. It is considered sufficient to add the full license text in a dedicated file in the root directory. Often this file is called 'LICENCE', 'LICENSE' or 'COPYING'. [REUSE](https://reuse.software) suggests to create a 'LICENSES' folder which holds all license texts. This is also well suited when multiple licenses are involved.
- Important: Make a clear statement about the license of the project. It is considered sufficient to add the full license
text in a dedicated file in the root directory.
Often this file is called 'LICENCE', 'LICENSE' or 'COPYING'. [REUSE](https://reuse.software) suggests to create a
'LICENSES' folder which holds all license texts. This is also well suited when multiple licenses are involved.
- Highly recommended: Add copyright and license information to each source file.
- Recommended but not necessary: Follow the [tutorial for becoming "REUSE-compliant"](https://reuse.software/tutorial/).
@ -48,26 +68,49 @@ We recommend to follow these steps to avoid ambiguities:
One of the major distinctions between licenses is between:
1. Licenses which guarantee the perpetual openness of the code, i.e. forever-open licenses. This is commonly obtained by a mechanism called "copyleft" which requires redistributing any derivative work using the same license again. The GPL licenses belong to this category. Other mechanisms to achieve the perpetual openness of the code include contractual law, but that is rarely used for software licenses.
1. Licenses which guarantee the perpetual openness of the code, i.e. forever-open licenses.
This is commonly obtained by a mechanism called "copyleft" which requires redistributing any derivative work using the
same license again. The GPL licenses belong to this category. Other mechanisms to achieve the perpetual openness of
the code include contractual law, but that is rarely used for software licenses.
2. Licenses which permit to close the source, i.e. temporarily-open licenses. These licenses are usually known as permissive licenses. The MIT license or the Apache license belong to this category.
The term "permissive" often causes confusion, because it sounds fair and good to unexperienced people. People who contribute to the development of a program released with a permissive license must be aware that the program could become proprietary at any time. For example, when a company hires the original team of developers.
2. Licenses which permit to close the source, i.e. temporarily-open licenses.
These licenses are usually known as permissive licenses. The MIT license or the Apache license belong to this category.
The term "permissive" often causes confusion, because it sounds fair and good to unexperienced people.
People who contribute to the development of a program released with a permissive license must be aware that the
program could become proprietary at any time. For example, when a company hires the original team of developers.
If all copyright holders agree, a project can always be forked into a project with a different license. Therefore, the larger the number of developers, the more difficult it is to make such a change.
If all copyright holders agree, a project can always be forked into a project with a different license.
Therefore, the larger the number of developers, the more difficult it is to make such a change.
There is no general rule for choosing one type of license or the other in every situation, but we encourage using copyleft licenses whenever possible.
There is no general rule for choosing one type of license or the other in every situation, but we encourage using
copyleft licenses whenever possible.
### Free vs. non-free licenses
Free software licenses are licenses which respect the [four fundamental software freedoms](https://www.gnu.org/philosophy/free-sw.en.html#four-freedoms) defined by the Free Software Foundation.
Both copyleft and permissive license can, or cannot, be free licenses. For example, the [Modified BSD license](https://www.gnu.org/licenses/license-list.en.html#ModifiedBSD) is a permissive non-copyleft free software license.
Free software licenses are licenses which respect the [four fundamental software freedoms](https://www.gnu.org/philosophy/free-sw.en.html#four-freedoms)
defined by the Free Software Foundation.
Both copyleft and permissive license can, or cannot, be free licenses. For example, the [Modified BSD license](https://www.gnu.org/licenses/license-list.en.html#ModifiedBSD)
is a permissive non-copyleft free software license.
In the context of licenses, the term "free" means free as in "freedom", not of gratis, but this has often been confused. Still, free software is often also gratis software.
Gratis non-free software usually includes gratis proprietary programs (shareware), demonstration or trial versions, limited versions (crippleware), advertising-supported software (e.g. antivirus), and usually viruses and worms (the victim doesn't pay to get them).
In the context of licenses, the term "free" means free as in "freedom", not of gratis, but this has often been confused.
Still, free software is often also gratis software.
Gratis non-free software usually includes gratis proprietary programs (shareware), demonstration or trial versions,
limited versions (crippleware), advertising-supported software (e.g. antivirus), and usually viruses and worms
(the victim doesn't pay to get them).
### Patent usage
Some permissive/temporarily-open licenses like the MIT license do not contain a patent provision granting the users the right to use their patents. For example, the code might be licensed under the MIT license, but implements an algorithm which is protected by a patent. In this case, the license might allow to copy, modify and distribute the code but at the same time does not guarantee the right to use the patented algorithm. It is a common argument in favour of the MIT license to claim that no public lawsuit has ever been conducted yet. Still, the threat to be sued remains, and it can be used to exert pressure. Some, if not most, license disputes moreover are settled even [before reaching the court](https://www.gnu.org/philosophy/enforcing-gpl.en.html) and could therefore leave no trace. Even Google [avoided the use of the MIT license when developing Android](https://source.android.com/setup/start/licenses), presumably because of the missing patent provision.
Some permissive/temporarily-open licenses like the MIT license do not contain a patent provision granting the users the
right to use their patents.
For example, the code might be licensed under the MIT license, but implements an algorithm which is protected by a patent.
In this case, the license might allow to copy, modify and distribute the code but at the same time does not guarantee
the right to use the patented algorithm.
It is a common argument in favour of the MIT license to claim that no public lawsuit has ever been conducted yet.
Still, the threat to be sued remains, and it can be used to exert pressure. Some, if not most, license disputes moreover
are settled even [before reaching the court](https://www.gnu.org/philosophy/enforcing-gpl.en.html) and could therefore
leave no trace.
Even Google [avoided the use of the MIT license when developing Android](https://source.android.com/setup/start/licenses),
presumably because of the missing patent provision.
For further information on "patents and free software", head over to [this wikipedia article](https://en.wikipedia.org/wiki/Software_patents_and_free_software).
@ -75,56 +118,106 @@ For further information on "patents and free software", head over to [this wikip
### License proliferation
Over the years, hundreds of different software/artwork licenses have been written, used and abandoned. This causes a big harm to the Free and Open Source community because it makes it more difficult for everybody to understand their meaning and compatibility between them. A common reaction of developers is to refuse discussions about licenses or their use altogether. Rather than dispersing efforts in a multitude of isolated and incompatible efforts ([license proliferation](https://en.wikipedia.org/wiki/License_proliferation)), we recommend using whenever possible only the mainstream licenses as highlighted in this page.
Over the years, hundreds of different software/artwork licenses have been written, used and abandoned.
This causes a big harm to the Free and Open Source community because it makes it more difficult for everybody to
understand their meaning and compatibility between them.
A common reaction of developers is to refuse discussions about licenses or their use altogether.
Rather than dispersing efforts in a multitude of isolated and incompatible efforts ([license proliferation](https://en.wikipedia.org/wiki/License_proliferation)),
we recommend using whenever possible only the mainstream licenses as highlighted in this page.
### License incompatibilities
It can occur that different projects, licensed with different open-source licenses, cannot be used together in a single, often larger, project because the licenses require incompatible conditions.
Some licenses, in fact, impose on developers (thanks to the power granted by copyright law) some restrictions/obligations on any [derivative work](https://en.wikipedia.org/wiki/Derivative_work). The term "derivative work" has a precise meaning in copyright law: For example, when developers modify the source code written by somebody else, they have created a derivative work.
As an example, if program A is licensed under GPL version 3 and program B is licensed under the Microsoft Public License ([MS-PL](https://directory.fsf.org/wiki/License:MS-PL)), the GPL requires to re-license any derivative work based on both programs A and B again under GPL, while the MS-PL requires to re-license the derivative work under MS-PL: the two conditions are incompatible with each other.
The incompatibility between licenses is clearly a headache for every developer. A possible way out, and the one we recommend, is to use only mainstream licenses (as recommended in this page) and hence avoid [license proliferation](#license-proliferation).
It can occur that different projects, licensed with different open-source licenses, cannot be used together in a single,
often larger, project because the licenses require incompatible conditions.
Some licenses, in fact, impose on developers (thanks to the power granted by copyright law) some
restrictions/obligations on any [derivative work](https://en.wikipedia.org/wiki/Derivative_work).
The term "derivative work" has a precise meaning in copyright law: For example, when developers modify the source code
written by somebody else, they have created a derivative work.
As an example, if program A is licensed under GPL version 3 and program B is licensed under the Microsoft Public License
([MS-PL](https://directory.fsf.org/wiki/License:MS-PL)), the GPL requires to re-license any derivative work based on
both programs A and B again under GPL, while the MS-PL requires to re-license the derivative work under MS-PL: the two
conditions are incompatible with each other.
The incompatibility between licenses is clearly a headache for every developer. A possible way out, and the one we
recommend, is to use only mainstream licenses (as recommended in this page) and hence avoid [license proliferation](#license-proliferation).
For more information on license compatibility, we recommend the commented [license list curated by the GNU project](https://www.gnu.org/licenses/license-list.html).
### Conflict-of-interests
The open-source community is represented by a variety of groups with different, and sometimes opposite, interests. For example, the prominent websites [ChooseALicense.com](https://choosealicense.com) is curated by GitHub and can be assumed to reflect at least partially the interests of Microsoft; this website presents, for example GPL last on the front page and it is silent about the missing patent clause in the MIT license both in the front page and in the [dedicated page](https://choosealicense.com/licenses/mit/). Moreover, the wording "I want it simple and permissive" can induce people to favour the MIT license; laypeople will want to have legal matters simple, and "permissive" sounds like fair and good.
When reading articles on licenses (including this one), we recommend exercising discretion by inspecting the governance of the source and the risk of conflicting interests.
The open-source community is represented by a variety of groups with different, and sometimes opposite, interests.
For example, the prominent websites [ChooseALicense.com](https://choosealicense.com) is curated by GitHub and can be
assumed to reflect at least partially the interests of Microsoft; this website presents, for example GPL last on the
front page and it is silent about the missing patent clause in the MIT license both in the front page and in the
[dedicated page](https://choosealicense.com/licenses/mit/).
Moreover, the wording "I want it simple and permissive" can induce people to favour the MIT license; laypeople will want
to have legal matters simple, and "permissive" sounds like fair and good.
When reading articles on licenses (including this one), we recommend exercising discretion by inspecting the governance
of the source and the risk of conflicting interests.
### Contributor license agreement (CLA)
A [contributor license agreement](https://en.wikipedia.org/wiki/Contributor_License_Agreement) may be forced upon a developer (e.g. by an employer), and may contain clauses which effectively void the spirit of certain open-source licenses. For example, a single company may advertise a project (for example for marketing reasons) under a GPL license, but on the other hand could require all its contributors to assign their copyright to the company. In this way the company could at any time (by being the only copyright holder) change the license from GPL to a proprietary license.
A [contributor license agreement](https://en.wikipedia.org/wiki/Contributor_License_Agreement) may be forced upon a
developer (e.g. by an employer), and may contain clauses which effectively void the spirit of certain open-source licenses.
For example, a single company may advertise a project (for example for marketing reasons) under a GPL license, but on
the other hand could require all its contributors to assign their copyright to the company.
In this way the company could at any time (by being the only copyright holder) change the license from GPL to a
proprietary license.
## Recommendations for software, hardware and other projects
### Software projects
For software projects, we recommend whenever possible to utilize a copyleft license. The only well-established licenses of this type are those of the GNU General Public License (GPL) family. The GPL licenses have evolved over time and come with different versions. Unfortunately, some versions are not compatible with older ones. To avoid [license proliferation](#license-proliferation) and to ease compatibility with future versions, we recommend using the "GNU Affero General Public License v3.0 or later" with SPDX license identifier ["AGPL-3.0-or-later"](https://spdx.org/licenses/AGPL-3.0-or-later.html). The AGPL provides the maximum openness of the code: Even when the software runs on a server, users who interact with that software (e.g. over a network connection) are entitled to receive a copy of the source code.
The [Affero GPL v3.0](https://www.gnu.org/licenses/agpl-3.0.en.html) is compatible with the [GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) and vice-versa thanks to article 13 in each license.
For software projects, we recommend whenever possible to utilize a copyleft license.
The only well-established licenses of this type are those of the GNU General Public License (GPL) family.
The GPL licenses have evolved over time and come with different versions. Unfortunately, some versions are not
compatible with older ones.
To avoid [license proliferation](#license-proliferation) and to ease compatibility with future versions, we recommend
using the "GNU Affero General Public License v3.0 or later" with SPDX license identifier ["AGPL-3.0-or-later"](https://spdx.org/licenses/AGPL-3.0-or-later.html).
The AGPL provides the maximum openness of the code: Even when the software runs on a server, users who interact with
that software (e.g. over a network connection) are entitled to receive a copy of the source code.
The [Affero GPL v3.0](https://www.gnu.org/licenses/agpl-3.0.en.html) is compatible with the [GPL v3.0](https://www.gnu.org/licenses/gpl-3.0.en.html)
and vice-versa thanks to article 13 in each license.
If using AGPL-3.0-or-later is not an option, we recommend using another license of the GNU family, such as the General Public License (GPL), or the Lesser General Public License (LGPL), always indicating the version "**v3.0 or later**".
In some cases, such as when writing certain libraries, using the Lesser General Public License (LGPL) may lead to a broader usage. In such cases, the [LGPL is preferred over the (A)GPL](https://www.gnu.org/licenses/gpl-faq.en.html#WhySomeGPLAndNotLGPL).
For software which is not very long (e.g. less than 300 lines of code) or unimportant, rather than using a copyleft license you may consider using a [lax permissive license instead](https://www.gnu.org/licenses/gpl-faq.en.html#WhatIfWorkIsShort).
If using AGPL-3.0-or-later is not an option, we recommend using another license of the GNU family, such as the General
Public License (GPL), or the Lesser General Public License (LGPL), always indicating the version "**v3.0 or later**".
In some cases, such as when writing certain libraries, using the Lesser General Public License (LGPL) may lead to a
broader usage. In such cases, the [LGPL is preferred over the (A)GPL](https://www.gnu.org/licenses/gpl-faq.en.html#WhySomeGPLAndNotLGPL).
For software which is not very long (e.g. less than 300 lines of code) or unimportant, rather than using a copyleft
license you may consider using a [lax permissive license instead](https://www.gnu.org/licenses/gpl-faq.en.html#WhatIfWorkIsShort).
If you are not allowed to, or if you do not want to use a forever-open license (for example because the company you work for does not allow you to do so) we recommend using a temporarily-open or permissive (in the sense that it permits users to close source the code) license which contains a patent provision. To avoid [proliferation of licenses](#license-proliferation), we recommend therefore to use the Apache license version 2.0 (SPDX license identifier Apache-2.0).
If you are not allowed to, or if you do not want to use a forever-open license (for example because the company you work
for does not allow you to do so) we recommend using a temporarily-open or permissive (in the sense that it permits users
to close source the code) license which contains a patent provision. To avoid [proliferation of licenses](#license-proliferation),
we recommend therefore to use the Apache license version 2.0 (SPDX license identifier Apache-2.0).
We recommend following the guidelines defined by the [GNU project](https://www.gnu.org/licenses/licenses.html). They are recommended by the [Free Software Foundation](https://fsf.org), too.
We recommend following the guidelines defined by the [GNU project](https://www.gnu.org/licenses/licenses.html).
They are recommended by the [Free Software Foundation](https://fsf.org), too.
### Hardware projects
We distinguish primarily between two families of hardware projects:
1. Hardware projects with little or no software dependencies (e.g. projects containing CAD drawings)
2. Hardware projects containing important software dependencies (e.g. the design of an integrated circuit) where compatibility issues with other licenses may arise
2. Hardware projects containing important software dependencies (e.g. the design of an integrated circuit) where
compatibility issues with other licenses may arise
In the first case, we recommend the use of the CERN Open Hardware License Version 2 - Strongly Reciprocal (SPDX license identifier: CERN-OHL-S-2.0). This license guarantees the forever-openness of the project as well as the actual hardware objects, but is incompatible with other mainstream licenses like those of the GNU-GPL family.
In the first case, we recommend the use of the CERN Open Hardware License Version 2 - Strongly Reciprocal
(SPDX license identifier: CERN-OHL-S-2.0).
This license guarantees the forever-openness of the project as well as the actual hardware objects, but is incompatible
with other mainstream licenses like those of the GNU-GPL family.
In the second case, there is currently no copyleft/forever-open license with wide license compatibility which is able to protect a hardware device. This is primarily due to the fact that hardware objects are not protected by copyright law. While awaiting for the appearance of a suited license, we recommend the use the "GNU Affero General Public License v3.0 or later" whenever the use of a CERN Open Hardware License is not permitted.
In the second case, there is currently no copyleft/forever-open license with wide license compatibility which is able to
protect a hardware device. This is primarily due to the fact that hardware objects are not protected by copyright law.
While awaiting for the appearance of a suited license, we recommend the use the "GNU Affero General Public License v3.0
or later" whenever the use of a CERN Open Hardware License is not permitted.
For hardware projects which should allow creating proprietary forks and/or proprietary hardware objects a license can be used as described in the next section.
For hardware projects which should allow creating proprietary forks and/or proprietary hardware objects a license can be
used as described in the next section.
### Other projects (documentation, music, etc.)
For documentation, writing, and other non-code assets, a [Creative Commons (CC)](https://creativecommons.org/about/cclicenses/) license can be used, but note that only the following CC licenses are considered free (sorted from protective to unconditional):
For documentation, writing, and other non-code assets, a [Creative Commons (CC)](https://creativecommons.org/about/cclicenses/)
license can be used, but note that only the following CC licenses are considered free
(sorted from protective to unconditional):
- [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/)
- [CC-BY](https://creativecommons.org/licenses/by/4.0/)
@ -140,4 +233,5 @@ We do not curate our own FAQ. Instead we redirect to other major collections:
- [Contributor's Frequently Asked Questions (FAQ) guide](https://www.fsf.org/licensing/contributor-faq)
- [Licensing and Compliance Lab: The most frequently asked Frequently Asked Questions](https://www.fsf.org/blogs/licensing/licensing-and-compliance-lab-the-most-frequently-asked-frequently-asked-questions)
If you have further questions on licensing, feel free to reach out to our community Matrix channels. Access links are provided at the [contact page](/contact/).
If you have further questions on licensing, feel free to reach out to our community Matrix channels. Access links are
provided at the [contact page](/contact/).

39
content/getting-started/what-is-codeberg.md
View file

@ -9,7 +9,8 @@ eleventyNavigation:
Codeberg is a democratic community-driven, non-profit software development platform operated
by Codeberg e.V. and centered around Codeberg.org, a Forgejo-based software forge.
On Codeberg you can develop your own [Free Software](https://simple.wikipedia.org/wiki/Free_software) projects, contribute to other
On Codeberg you can develop your own [Free Software](https://simple.wikipedia.org/wiki/Free_software) projects,
contribute to other
projects, [browse](https://codeberg.org/explore) through inspiring and useful
free software, share your knowledge or build your projects a home on the web
using [Codeberg Pages](/codeberg-pages), just to name a few.
@ -20,26 +21,40 @@ privacy-friendly alternative to commercial services such as GitHub.
## Our Mission
The development of Free and Open Source Software is experiencing an unbroken boom, due to the general availability of the internet and the resulting social network effects, multiplying communication, exchange of ideas, and productivity each and every month.
The development of Free and Open Source Software is experiencing an unbroken boom, due to the general availability of
the internet and the resulting social network effects, multiplying communication, exchange of ideas,
and productivity each and every month.
The number of developers and projects participating in the Open Source movement is growing exponentially.
Only new software tools and collaboration platforms made these dynamics possible and manageable.
While all successful software tools that enabled this development were contributed by the Free and Open Source Software community, commercial for-profit platforms dominate the hosting of the results of our collaborative work.
This has led to the paradox that literally millions of volunteers create, collect, and maintain invaluable knowledge, documentation, and software, to feed closed platforms driven by commercial interests, whose program is neither visible nor controllable from outside.
While all successful software tools that enabled this development were contributed by the Free and Open Source Software
community, commercial for-profit platforms dominate the hosting of the results of our collaborative work.
This has led to the paradox that literally millions of volunteers create, collect, and maintain invaluable knowledge,
documentation, and software, to feed closed platforms driven by commercial interests, whose program is neither visible
nor controllable from outside.
Considering the fate of formerly successful startups like SourceForge, we need to break the circle and avoid history repeating.
The mission of Codeberg e.V. is to build and maintain a free collaboration platform for creating, archiving, and preserving code and to document its development process.
The mission of Codeberg e.V. is to build and maintain a free collaboration platform for creating, archiving, and
preserving code and to document its development process.
Dependencies on commercial, external, or proprietary services for the operation of the platform are avoided, in order to guarantee independence and reliability.
Dependencies on commercial, external, or proprietary services for the operation of the platform are avoided, in order to
guarantee independence and reliability.
Read more at [Codeberg's initial announcement](https://blog.codeberg.org/codebergorg-launched.html) and the [Licensing article](/getting-started/licensing).
Read more at [Codeberg's initial announcement](https://blog.codeberg.org/codebergorg-launched.html)
and the [Licensing article](/getting-started/licensing).
## Codeberg vs. Forgejo
[Forgejo](https://forgejo.org) is self-hostable free software for software development, built on top of Git. Codeberg is powered by Forgejo, which is in turn a [hard-fork](https://forgejo.org/2024-02-forking-forward/) of Gitea. Compared to Codeberg, Forgejo is not one service, but free software to help you build your own. Everyone can install their own Forgejo instance to host their own projects. There are also public Forgejo instances as well as Codeberg you can use, but make sure you find a site that is actively maintained and updated, and that you trust the provider.
[Forgejo](https://forgejo.org) is self-hostable free software for software development, built on top of Git.
Codeberg is powered by Forgejo, which is in turn a [hard-fork](https://forgejo.org/2024-02-forking-forward/) of Gitea.
Compared to Codeberg, Forgejo is not one service, but free software to help you build your own.
Everyone can install their own Forgejo instance to host their own projects.
There are also public Forgejo instances as well as Codeberg you can use, but make sure you find a site that is actively
maintained and updated, and that you trust the provider.
The codebase history of Forgejo and its predecessors predates Codeberg.
However, since 2022, [Codeberg is backing the development of Forgejo](https://blog.codeberg.org/codeberg-launches-forgejo.html) as an umbrella organization.
However, since 2022, [Codeberg is backing the development of Forgejo](https://blog.codeberg.org/codeberg-launches-forgejo.html)
as an umbrella organization.
People are often asking why they should use Codeberg over other Forgejo instances. The most important reasons are:
@ -58,7 +73,8 @@ of the platform, but if you want you can [join Codeberg e.V.](https://join.codeb
support the project financially, be informed about Codeberg and, optionally, to actively
contribute to the association.
Codeberg members can also take part in the decisions of the platform as explained in the [bylaws](https://codeberg.org/Codeberg/org/src/en/bylaws.md), and they elect the presidium and board of the platform, thus Codeberg can be considered as community-owned.
Codeberg members can also take part in the decisions of the platform as explained in the [bylaws](https://codeberg.org/Codeberg/org/src/en/bylaws.md),
and they elect the presidium and board of the platform, thus Codeberg can be considered as community-owned.
## Alternatives to Codeberg
@ -76,7 +92,8 @@ We'll list a few options:
They do offer much more than Forgejo, so check them out in any case.
- [other public Forgejo instances](https://codeberg.org/forgejo-contrib/delightful-forgejo#user-content-public-instances)
- Self-Hosting [Forgejo](https://forgejo.org), the software that powers Codeberg.
- [SourceHut](https://sourcehut.org): A minimum-GUI Free Software based service, available as hosted version by a transparent for-profit. Self-Hostable.
- [SourceHut](https://sourcehut.org): A minimum-GUI Free Software based service, available as hosted version by a
transparent for-profit. Self-Hostable.
---

27
content/getting-started/wiki.md
View file

@ -6,7 +6,8 @@ eleventyNavigation:
order: 60
---
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis to collect knowledge and share information.
A [wiki](https://en.wikipedia.org/wiki/Wiki) is a collaborative space on the web. It is a common practice to use wikis
to collect knowledge and share information.
Codeberg allows you to add a wiki to a repo for additional documentation.
The user in these examples is `knut`, the polar bear and its repository is `foobar`.
@ -22,7 +23,8 @@ To enable the wiki for a repository follow these steps:
{% admonition "warning" %}
Be aware that the wiki, once enabled, is accessible for _everyone_ who has `read` access to your repository - on public repositories even unauthenticated guests can access the wiki.
Be aware that the wiki, once enabled, is accessible for _everyone_ who has `read` access to your repository -
on public repositories even unauthenticated guests can access the wiki.
The wiki is _not_ a suitable place for storing private information or secrets (like passwords).
{% endadmonition %}
@ -33,20 +35,23 @@ To edit the wiki `write` permission to the repository is required.
The wiki is essentially a separate Git repo in your repository with a predefined name in the form of `<your-repository-name>.wiki.git`.
It consists of [Markdown](https://en.wikipedia.org/wiki/Markdown) files (file extension `.md`) and additional assets like images.
It consists of [Markdown](https://en.wikipedia.org/wiki/Markdown) files (file extension `.md`) and additional assets
like images.
No further stylesheets are needed. The Markdown files are automatically rendered according to the selected Codeberg theme.
## Adding content via web
After you have enabled the wiki you are prompted to create the initial page `Home.md`.
The web UI in your browser is currently limited to adding, updating, and deleting pages; you can't manage assets like images this way.
The web UI in your browser is currently limited to adding, updating, and deleting pages; you can't manage assets like
images this way.
<img src="/images/getting-started/wiki/wiki_pageview.png" alt="Wiki home page with edit buttons">
### Adding external images via web
If you cannot [use a local Git client](#adding-external-images-via-web), linking to _external_ assets like images is still possible.
If you cannot [use a local Git client](#adding-external-images-via-web), linking to _external_ assets like images is
still possible.
<img src="/images/getting-started/wiki/wiki_pageview.png" alt="Web editor with an arrow pointing at the "Insert Image" button">
@ -56,7 +61,8 @@ You can read up more on how it works [in a later section](#describing-images-in-
## Adding content using a local Git client
You can work with the wiki repo as you would with any other Git repo on Codeberg; see our docs about managing a Git repo [via CLI](https://docs.codeberg.org/git/clone-commit-via-cli).
You can work with the wiki repo as you would with any other Git repo on Codeberg; see our docs about managing a Git repo
[via CLI](https://docs.codeberg.org/git/clone-commit-via-cli).
```shell
git clone git@codeberg.org:knut/foobar.wiki.git
@ -65,7 +71,8 @@ nano Home.md # or your editor of choice
git commit -am "create Home page"
```
Editing locally allows you to use your favorite editor (preferably with Markdown syntax check and highlighting) and manage additional assets like images.
Editing locally allows you to use your favorite editor (preferably with Markdown syntax check and highlighting) and
manage additional assets like images.
### Adding images using a local Git client
@ -111,7 +118,8 @@ In contrast to embedding external images, images in Git are only rendered after
## Adding a sidebar and a footer
To enhance the usability of your wiki you can add a custom sidebar and a footer that are shown on every page. The sidebar will be displayed to the right of the main content and the footer below.
To enhance the usability of your wiki you can add a custom sidebar and a footer that are shown on every page.
The sidebar will be displayed to the right of the main content and the footer below.
To enable the sidebar, just add a file named `_Sidebar.md` to your wiki. For a footer the file must be named `_Footer.md`.
Both file types allow common Markdown syntax to adjust the presentation to your needs.
@ -130,7 +138,8 @@ Very basic example for a sidebar:
{% admonition "tip" %}
These files starting with `_` are hidden, so in the web UI you need to manually browse for the files. E.g. for our user _knut_ and his _foobar_ repo:
These files starting with `_` are hidden, so in the web UI you need to manually browse for the files.
E.g. for our user _knut_ and his _foobar_ repo:
`https://codeberg.org/knut/foobar/wiki/_Sidebar`
{% endadmonition %}

32
content/git/clone-commit-via-cli.md
View file

@ -8,9 +8,12 @@ eleventyNavigation:
# Git workflow
Cloning, editing, committing, pushing and pulling can be performed using Git directly from the command line, by using a Git client, or via the web interface. The former option is shown below. The latter option is detailed in the section [Clone & Commit via Web](/git/clone-commit-via-web).
Cloning, editing, committing, pushing and pulling can be performed using Git directly from the command line,
by using a Git client, or via the web interface. The former option is shown below.
The latter option is detailed in the section [Clone & Commit via Web](/git/clone-commit-via-web).
The user in these examples is `knut` the polar bear, and its repository is `examples`. The repository was created via the Codeberg website, including a `README.md` file.
The user in these examples is `knut` the polar bear, and its repository is `examples`.
The repository was created via the Codeberg website, including a `README.md` file.
## Clone
@ -61,12 +64,16 @@ Modify an existing file:
~/examples$ nano README.md
```
For illustrative purposes, we will use the [`nano` text editor](https://www.nano-editor.org/) in this tutorial. You can still use your own text editor if you wish to.
For illustrative purposes, we will use the [`nano` text editor](https://www.nano-editor.org/) in this tutorial.
You can still use your own text editor if you wish to.
## Commit
A _commit_ is a record of the changes to the repository. This is like a snapshot of your edits.
A commit requires a commit message. For the example below, the message is "test". Keep in mind that "test" is not a very informative message, though. In the real world, make sure your commit message is informative, for you, your collaborators and anyone who might be interested in your work. Advice on how to write a good commit message can be found on countless websites and blogs.
A commit requires a commit message. For the example below, the message is "test".
Keep in mind that "test" is not a very informative message, though. In the real world, make sure your commit message is
informative, for you, your collaborators and anyone who might be interested in your work.
Advice on how to write a good commit message can be found on countless websites and blogs.
Add a commit:
@ -85,7 +92,8 @@ Here's an explanation of the command flags used here:
The last step is to synchronize (_push_) the commit from the local repository to the remote one on Codeberg.
If you are using HTTPS, you will be asked for your Codeberg username and password. If you want to avoid entering your password every time, consider [using SSH](/security/ssh-key) instead.
If you are using HTTPS, you will be asked for your Codeberg username and password. If you want to avoid entering your
password every time, consider [using SSH](/security/ssh-key) instead.
```shell
~/examples$ git push
@ -103,23 +111,29 @@ To https://codeberg.org/knut/examples.git
## Pull
_Pulling_ synchronizes the modifications (commit) from the remote repository on Codeberg to the local one.
Pulling is important when you're working on different computers, to make sure that all computers are on the same page. It's even more important when you have collaborators on a project; they may change the files as well, so you need to pull these modifications before you start working.
Pulling is important when you're working on different computers, to make sure that all computers are on the same page.
It's even more important when you have collaborators on a project; they may change the files as well, so you need to
pull these modifications before you start working.
Because of this, it is recommended to pull before pushing.
# CLI clients `tea` and `berg` for other actions
## Gitea / Forgejo CLI `tea`
[`tea`](https://gitea.com/gitea/tea) is a general CLI client that can be used with instances of [Gitea](https://gitea.com) and [Forgejo](https://forgejo.org). Since Codeberg runs on Forgejo, you can use `tea` with it.
[`tea`](https://gitea.com/gitea/tea) is a general CLI client that can be used with instances of [Gitea](https://gitea.com)
and [Forgejo](https://forgejo.org). Since Codeberg runs on Forgejo, you can use `tea` with it.
This project is maintained by [the Gitea project](https://gitea.com).
## Codeberg CLI `berg`
The [codeberg-cli project](https://codeberg.org/RobWalt/codeberg-cli), aka. `berg`, is a CLI client that is tailored for Codeberg. The main difference compared to `tea` are:
The [codeberg-cli project](https://codeberg.org/RobWalt/codeberg-cli), aka. `berg`, is a CLI client that is tailored
for Codeberg.
The main difference compared to `tea` are:
- extra features: `berg` provides some features that `tea` doesn't implement, like editing issues or pull requests
- active development: the `berg` repository is actively developed and maintained by a few community members
- modern UI: `berg` offers an interactive and modern looking user experience
If you're interested, check out the [codeberg-cli wiki](https://codeberg.org/RobWalt/codeberg-cli/wiki), which contains just about everything you need to know about it.
If you're interested, check out the [codeberg-cli wiki](https://codeberg.org/RobWalt/codeberg-cli/wiki), which contains
just about everything you need to know about it.

30
content/git/clone-commit-via-web.md
View file

@ -6,9 +6,11 @@ eleventyNavigation:
order: 30
---
As shown before, cloning, editing, committing, pushing and pulling can be performed using Git directly from the command line. This time, we're going to do this all through the web interface.
As shown before, cloning, editing, committing, pushing and pulling can be performed using Git directly from the command line.
This time, we're going to do this all through the web interface.
The user in these examples is `knut` the polar bear and its repository is `foobar`. The repository was created via the Codeberg website including a `README.md` file.
The user in these examples is `knut` the polar bear and its repository is `foobar`.
The repository was created via the Codeberg website including a `README.md` file.
## Clone
@ -18,7 +20,8 @@ Copy the repo URL from the Codeberg website to your Git client using the `Copy`
{% admonition "tip" %}
If you want to download a copy of a specific state of the repository without its version history, click on the `Download Repository` icon to download either as ZIP or TAR.GZ.
If you want to download a copy of a specific state of the repository without its version history,
click on the `Download Repository` icon to download either as ZIP or TAR.GZ.
{% endadmonition %}
@ -32,7 +35,8 @@ The pencil tool (`Edit File`) will open a new window.
<img src="/images/git/clone-commit-via-web/edit1.png" alt="edit1">
Here, you can edit the file as you wish.
The `Preview` tab shows you how the file will look like when rendered, and `Preview Changes` will highlight the changes you've made to the file (red for deletions and green for additions).
The `Preview` tab shows you how the file will look like when rendered, and `Preview Changes` will highlight the changes
you've made to the file (red for deletions and green for additions).
<img src="/images/git/clone-commit-via-web/edit2.png" alt="edit2">
@ -44,9 +48,14 @@ The commit section is at the bottom of the edit window:
<img src="/images/git/clone-commit-via-web/commit.png" alt="commit">
A commit requires a commit message. A default message is added, but do not hesitate to edit it. Make sure your commit message is informative, for you, your collaborators and anyone who might be interested in your work. Some advice on how to write a good commit message can be found on countless websites and blogs!
A commit requires a commit message. A default message is added, but do not hesitate to edit it.
Make sure your commit message is informative, for you, your collaborators and anyone who might be interested in your work.
Some advice on how to write a good commit message can be found on countless websites and blogs!
If you intend to start a pull request with this commit, you should choose the option `Create a new branch for this commit and start a pull request`. This will make it easier to work on the different commits without mixing them if they are in different forks. Check the documentation on [Pull requests and Git flow](/collaborating/pull-requests-and-git-flow) for more details.
If you intend to start a pull request with this commit, you should choose the option
`Create a new branch for this commit and start a pull request`.
This will make it easier to work on the different commits without mixing them if they are in different forks.
Check the documentation on [Pull requests and Git flow](/collaborating/pull-requests-and-git-flow) for more details.
Submit your changes by clicking on `Commit Changes`.
@ -55,7 +64,10 @@ Submit your changes by clicking on `Commit Changes`.
Synchronizing the modifications (commit) from the local repository to the remote one on Codeberg is called _pushing_.
_Pulling_ synchronizes the modifications (commit) from the remote repository on Codeberg to the local one.
Pulling is important when you're working on different computers, to make sure that all computers are on the same page. It's even more important when you have collaborators on a project; they may change the files as well, so you need to pull these modifications before you start working.
Because of this, it's recommended to pull before pushing.
Pulling is important when you're working on different computers, to make sure that all computers are on the same page.
It's even more important when you have collaborators on a project; they may change the files as well, so you need to
pull these modifications before you start working. Because of this, it's recommended to pull before pushing.
Pushing and pulling only make sense if you work locally. This is why there is no "push" or "pull" button on the Codeberg web interface; committing here already pushes to the remote repository on Codeberg, and there is therefore nothing to pull (except pull requests of course).
Pushing and pulling only make sense if you work locally. This is why there is no "push" or "pull" button on the Codeberg
web interface; committing here already pushes to the remote repository on Codeberg,
and there is therefore nothing to pull (except pull requests of course).

14
content/git/configuring-git.md
View file

@ -5,14 +5,17 @@ eleventyNavigation:
parent: Git
---
Once you've managed to get Git up and running, the first thing you must do before you can use your fresh installation of Git is to tell Git your name and email address. You only have to do this once; this is easily done with:
Once you've managed to get Git up and running, the first thing you must do before you can use your fresh installation of
Git is to tell Git your name and email address. You only have to do this once; this is easily done with:
```bash
git config --global user.name 'knut'
git config --global user.email 'knut@example.com'
```
The username can be anything, but it is important that the email is the same as the one you use on Codeberg. This is because the email address will later be used to assign your commits to your account. To verify that you've set up everything properly, run:
The username can be anything, but it is important that the email is the same as the one you use on Codeberg.
This is because the email address will later be used to assign your commits to your account.
To verify that you've set up everything properly, run:
```bash
git config --global --list
@ -20,8 +23,11 @@ git config --global --list
{% admonition "tip" %}
If you don't want to include your email address with your commits, you can opt to specify `USERNAME@noreply.codeberg.org` here instead, where USERNAME is your Codeberg username.
If you don't want to include your email address with your commits, you can opt to specify `USERNAME@noreply.codeberg.org`
here instead, where USERNAME is your Codeberg username.
{% endadmonition %}
If you ever want to change your name or email address, simply run the corresponding command again. You could also omit the `--global` flag to set a username and email address only for the Git repository you're currently in.
If you ever want to change your name or email address, simply run the corresponding command again.
You could also omit the `--global` flag to set a username and email address only for the Git repository you're
currently in.

3
content/git/index.md
View file

@ -16,7 +16,8 @@ There are 2 ways to interact with a Git repository hosted on Codeberg:
Option 1 requires a Git client of your choice [installed on your local system](/getting-started/install-git/).
We recommend the use of the [SSH protocol](https://en.wikipedia.org/wiki/Secure_Shell_Protocol).
It offers improved security through key-based access (stronger protection than a regular password) and better ease of use (no need to provide credentials on every push).
It offers improved security through key-based access (stronger protection than a regular password) and better ease of
use (no need to provide credentials on every push).
{% assign navPages = collections.all | eleventyNavigation %}
{%- for entry in navPages %}

5
content/git/squash-commits.md
View file

@ -6,7 +6,10 @@ eleventyNavigation:
order: 50
---
Sometimes you'll want to merge multiple commits into one. Maybe the commits are "dirty", full of non-working code or embarrassing commit messages. The solution shown here is only one of many possible solutions. See this [StackOverflow question](https://stackoverflow.com/q/2563632/4865723) for more details.
Sometimes you'll want to merge multiple commits into one. Maybe the commits are "dirty", full of non-working code or
embarrassing commit messages.
The solution shown here is only one of many possible solutions.
See this [StackOverflow question](https://stackoverflow.com/q/2563632/4865723) for more details.
Here is an example.

21
content/git/using-lfs.md
View file

@ -7,10 +7,12 @@ eleventyNavigation:
---
Storing large files in Git is usually a bad idea.
They're contained in its history forever, and they enlarge your repository size, which annoys your contributors and increases the cost of storage on Codeberg.
They're contained in its history forever, and they enlarge your repository size, which annoys your contributors and
increases the cost of storage on Codeberg.
However, there is a good way to do this:
Using [Git LFS (Large File Storage)][git-lfs], you can easily manage binary files, and remove them permanently when they are no longer necessary.
Using [Git LFS (Large File Storage)][git-lfs], you can easily manage binary files, and remove them permanently when they
are no longer necessary.
The files are still being tracked with Git, but the actual content is stored in a different place on the Codeberg servers.
@ -19,7 +21,8 @@ The files are still being tracked with Git, but the actual content is stored in
Git LFS is a command line plugin for Git.
You can install it from the [Git LFS Website][git-lfs], or via the package manager of your distribution.
A more detailed installation description can be found at the [Installation article](https://github.com/git-lfs/git-lfs/wiki/Installation) of the Git LFS wiki.
A more detailed installation description can be found at the [Installation article](https://github.com/git-lfs/git-lfs/wiki/Installation)
of the Git LFS wiki.
After you install Git LFS, it needs to be enabled in your Git configuration.
@ -39,7 +42,8 @@ To track files with Git LFS, the file and/or path-names must be configured to be
git lfs track $fileorpathname
```
You can add filenames, directories or even wild-card representations of files (e.g. `images/**` for all files in the `images/` directory, or `**.dat` for all files ending with `.dat`).
You can add filenames, directories or even wild-card representations of files
(e.g. `images/**` for all files in the `images/` directory, or `**.dat` for all files ending with `.dat`).
This creates a `.gitattributes` file containing (apart from other non LFS-related stuff) the configuration of Git LFS.
Be sure to add it to your repository as well.
@ -48,7 +52,8 @@ Be sure to add it to your repository as well.
git add .gitattributes
```
Now, you can work with Git as you would usually do. Add files with `git add`, commit with `git commit`, and then push with `git push`.
Now, you can work with Git as you would usually do. Add files with `git add`, commit with `git commit`, and then push
with `git push`.
Git LFS will transparently handle the use of LFS on the configured files for you.
As long as your `.gitattributes` file is present in the remote repository, you can just use Git as usual.
@ -117,7 +122,8 @@ Also keep in mind that all users must refresh their local repositories prior to
If you already have a large file in your repository, it won't automatically be moved to LFS just by enabling the tracking.
You can first run `git lfs migrate info` to see which files take up the most space in your repository. Append `--everything` to see the sizes of all files (even the smaller ones).
You can first run `git lfs migrate info` to see which files take up the most space in your repository.
Append `--everything` to see the sizes of all files (even the smaller ones).
Then you can run `git lfs migrate import` to import some or all files into using LFS.
@ -141,7 +147,8 @@ git lfs migrate export --include=\*.rnd --everything
This disables LFS for all files ending with .rnd in your repository.
The man page of [git-lfs-migrate(1)][git-lfs-migrate] further explains how to export files in order to disable tracking them by LFS.
The man page of [git-lfs-migrate(1)][git-lfs-migrate] further explains how to export files in order to disable tracking
them by LFS.
## Further reading

38
content/git/using-tags.md
View file

@ -8,23 +8,31 @@ eleventyNavigation:
## What are tags?
Tags are a feature in Git that can be used to make a snapshot of a repository from a point in time. It is generally used to mark releases (e.g. v1.2.4), and it functions as a shortcut to see what the repo looked like at the time.
Tags are a feature in Git that can be used to make a snapshot of a repository from a point in time.
It is generally used to mark releases (e.g. v1.2.4), and it functions as a shortcut to see what the repo looked like at
the time.
## What are releases?
Releases are a feature in Forgejo, independent of Git that allows you to attach files and release notes along with the source code at the time, and share it on Codeberg, linking to a Git tag.
Releases are a feature in Forgejo, independent of Git that allows you to attach files and release notes along with the
source code at the time, and share it on Codeberg, linking to a Git tag.
### Wait, what is the difference between tags and releases?
They are very similar, the difference being that tags are just the repository frozen in time and are part of Git (you can make a tag inside of Git), but releases are tags accompanied with a binary file and are not part of Git (you need to go to your Codeberg repository page to create a release).
They are very similar, the difference being that tags are just the repository frozen in time and are part of Git
(you can make a tag inside of Git), but releases are tags accompanied with a binary file and are not part of Git
(you need to go to your Codeberg repository page to create a release).
## Creating tags and releases
If you want to create tags, using Git is recommended. You can also create a new tag when creating a new release on Codeberg. Releases can be created using the Codeberg frontend or Codeberg's [API](https://codeberg.org/api/swagger#/repository/repoCreateRelease) — using Git to create new releases is not possible.
If you want to create tags, using Git is recommended. You can also create a new tag when creating a new release on Codeberg.
Releases can be created using the Codeberg frontend or Codeberg's [API](https://codeberg.org/api/swagger#/repository/repoCreateRelease)
— using Git to create new releases is not possible.
{% admonition "tip" %}
Tags are generally labelled by version numbers. It is good practice to prefix a version number with a `v` (e.g. `v1.2.3`) and to use the [Semantic Versioning](https://semver.org/) specification for assigning and incrementing version numbers.
Tags are generally labelled by version numbers. It is good practice to prefix a version number with a `v` (e.g. `v1.2.3`)
and to use the [Semantic Versioning](https://semver.org/) specification for assigning and incrementing version numbers.
{% endadmonition %}
@ -38,7 +46,8 @@ git tag -a <tag name> -m "<my tag message>"
You can omit `"<my tag message>"` to write a longer tag message in an editor window.
Tags are not automatically pushed when you run `git push` (compared to commits or branches). They have to be pushed manually to the remote target, like so:
Tags are not automatically pushed when you run `git push` (compared to commits or branches).
They have to be pushed manually to the remote target, like so:
```bash
git push --tags <remote target, probably "origin">
@ -52,15 +61,19 @@ git push <remote target, probably "origin"> <tag name, e.g., "v1.2.3">
### On Codeberg
To create a release on Codeberg, first go to your repository `Settings`, click on `Units` -> `Overview`, enable `Enable repository releases` and click on `Save setting`.
To create a release on Codeberg, first go to your repository `Settings`, click on `Units` -> `Overview`,
enable `Enable repository releases` and click on `Save setting`.
<img src="/images/collaborating/citable-code/enable_repository_releases.png" alt="Screenshot of an example repository's settings with circles drawn over the buttons described in the steps above">
<img
src="/images/collaborating/citable-code/enable_repository_releases.png"
alt="Screenshot of an example repository's settings with circles drawn over the buttons described in the steps above">
Then go to the `Releases` tab of your repository, and click on `New Release`:
<img src="/images/collaborating/citable-code/releases1.png" alt="releases1">
Here, enter a version number for your new release, select the branch that contains the code you want to release, and add a title and a description:
Here, enter a version number for your new release, select the branch that contains the code you want to release,
and add a title and a description:
<img src="/images/collaborating/citable-code/new-release.png" alt="new-release">
@ -76,5 +89,8 @@ Here, you can edit the release if needed, and you can also download the source c
<img src="/images/git/using-tags/tags.png" alt="tags">
To view the release, go to the releases tab (1) in the repository. Then locate the release you want to view. As an example, we will be looking at the `Added Knut!` release (2). If you just want to access the files attached to the release, you can download it from the `Downloads` dropdown (3).
If you want to see a snapshot of the source code at the time of the release, select a source code archive download (4) from the `Downloads` dropdown or click on the tag on the left side (5).
To view the release, go to the releases tab (1) in the repository. Then locate the release you want to view.
As an example, we will be looking at the `Added Knut!` release (2).
If you just want to access the files attached to the release, you can download it from the `Downloads` dropdown (3).
If you want to see a snapshot of the source code at the time of the release, select a source code archive download (4)
from the `Downloads` dropdown or click on the tag on the left side (5).

14
content/home.md
View file

@ -6,13 +6,15 @@ permalink: /
Welcome! We're here to help you when you're having issues or questions with Codeberg.
Please choose a section from the sidebar on the left, which you can toggle by clicking the three stripes at the top left corner of your browser window.
Please choose a section from the sidebar on the left, which you can toggle by clicking the three stripes at the top left
corner of your browser window.
If you're new to Codeberg, consider reading the [Getting Started Guide](/getting-started).
## Getting Help
Codeberg's Documentation mostly includes tutorials specific to using the platforms provided by _Codeberg_; they focus on the maintenance of open-source projects with the platforms provided by Codeberg (Forgejo, Woodpecker, Weblate, Pages, etc.).
Codeberg's Documentation mostly includes tutorials specific to using the platforms provided by _Codeberg_; they focus on
the maintenance of open-source projects with the platforms provided by Codeberg (Forgejo, Woodpecker, Weblate, Pages, etc.).
If what you are trying to do is not covered by our Documentation, the following resources can be helpful:
@ -22,6 +24,10 @@ If what you are trying to do is not covered by our Documentation, the following
### Contact
If you encounter a bug or if you can't find an answer to your question, feel free to open an issue to [the Codeberg Community Tracker](https://codeberg.org/Codeberg/Community/issues). This is the preferred way to report bugs to the software or ask questions if you can't find an answer somewhere else. You can also quickly find the Codeberg Issues using the footer.
If you encounter a bug or if you can't find an answer to your question,
feel free to open an issue to [the Codeberg Community Tracker](https://codeberg.org/Codeberg/Community/issues).
This is the preferred way to report bugs to the software or ask questions if you can't find an answer somewhere else.
You can also quickly find the Codeberg Issues using the footer.
There are more [places to chat with the community and the people that run Codeberg](/contact/); all of them have nice people that could help you.
There are more [places to chat with the community and the people that run Codeberg](/contact/); all of them have nice
people that could help you.

24
content/improving-codeberg/contributing-code.md
View file

@ -5,7 +5,8 @@ eleventyNavigation:
parent: ImprovingCodeberg
---
Hey there, thank you for heading here and your interest in improving Codeberg. This page is intended to give you a quick start on how and where to contribute code to the platform of Codeberg itself.
Hey there, thank you for heading here and your interest in improving Codeberg.
This page is intended to give you a quick start on how and where to contribute code to the platform of Codeberg itself.
The various projects move at their own pace,
so if you already know where you are going to contribute to,
check out their own contributing guides or get in touch with the maintainers.
@ -15,9 +16,11 @@ The following projects always need a helping hand:
- [Forgejo](https://forgejo.org/), the software that powers Codeberg.org and all the Git features
- [Weblate](https://weblate.org), the localization platform available at [translate.codeberg.org](https://translate.codeberg.org)
- [Woodpecker CI](https://woodpecker-ci.org), our hosted CI/CD solution.
- [Codeberg Pages](https://codeberg.org/Codeberg/pages-server/), a service that allows you to serve static websites from Git repositories, see [codeberg.page](https://codeberg.page)
- [Codeberg Pages](https://codeberg.org/Codeberg/pages-server/), a service that allows you to serve static websites from
Git repositories, see [codeberg.page](https://codeberg.page)
Also check out the [Codeberg](https://codeberg.org/Codeberg) and [Codeberg-Infrastructure](https://codeberg.org/Codeberg-Infrastructure) organizations, they contain numerous other software and setup projects that will appreciate your contributions.
Also check out the [Codeberg](https://codeberg.org/Codeberg) and [Codeberg-Infrastructure](https://codeberg.org/Codeberg-Infrastructure)
organizations, they contain numerous other software and setup projects that will appreciate your contributions.
## Getting Started
@ -33,15 +36,22 @@ The following issue trackers may contain a few ideas for things that could be wo
- [Codeberg Community Tracker](https://codeberg.org/Codeberg/Community/issues?&state=open&labels=338)
- [Forgejo Issue Tracker](https://codeberg.org/forgejo/forgejo/issues)
We also recommend working on changes that _personally_ bother you first. Something in the direction of simple UI changes changes would probably make the most sense, as they are the easiest to get started with and will help you get more acquainted with the codebase (which could help you solve more complicated problems later) in the process.
We also recommend working on changes that _personally_ bother you first. Something in the direction of simple UI changes
changes would probably make the most sense, as they are the easiest to get started with and will help you get more
acquainted with the codebase (which could help you solve more complicated problems later) in the process.
Solving easy problems helps a lot too! It makes Codeberg's underlying software look much more polished; it also lets other contributors use more of their limited time to solve very sophisticated or unexpected problems.
Solving easy problems helps a lot too! It makes Codeberg's underlying software look much more polished;
it also lets other contributors use more of their limited time to solve very sophisticated or unexpected problems.
In the _Codeberg Community Tracker_, there are some issues that are marked using the [`contribution welcome`](https://codeberg.org/Codeberg/Community/issues?&state=open&labels=105) tag. This tag is meant to show that we would really appreciate your help here. They also act as a good starting point if you are looking for something to work on.
In the _Codeberg Community Tracker_, there are some issues that are marked using the
[`contribution welcome`](https://codeberg.org/Codeberg/Community/issues?&state=open&labels=105) tag.
This tag is meant to show that we would really appreciate your help here.
They also act as a good starting point if you are looking for something to work on.
## More questions?
If you need help or feel stuck, need inspiration or advice, you can always reach out to us in our [Contributing to Codeberg Matrix Channel](https://matrix.to/#/#contributing-to-codeberg:kle.li).
If you need help or feel stuck, need inspiration or advice,
you can always reach out to us in our [Contributing to Codeberg Matrix Channel](https://matrix.to/#/#contributing-to-codeberg:kle.li).
A more comprehensive list of our chat rooms can be found in the [Codeberg Matrix Space](https://matrix.to/#/#codeberg-space:matrix.org).

10
content/improving-codeberg/donate.md
View file

@ -36,9 +36,12 @@ develop new features and sustain the Free Software ecosystem around.
BIC: GENODEF1SLR
</pre>
</p>
The following EPC QR code can be used to initiate a SEPA credit transfer. Notice it contains a default amount of 10 Euros, but you can change it to whatever amount you want to donate.
The following EPC QR code can be used to initiate a SEPA credit transfer.
Notice it contains a default amount of 10 Euros, but you can change it to whatever amount you want to donate.
<img src="/images/integrations/donate-10-euros.png" alt="European Payments Council (EPC) QR code to donate 10 euros to Codeberg e.V.">
<img
src="/images/integrations/donate-10-euros.png"
alt="European Payments Council (EPC) QR code to donate 10 euros to Codeberg e.V.">
</div>
</div>
@ -58,7 +61,8 @@ develop new features and sustain the Free Software ecosystem around.
### Receipts for donations / membership fees
Codeberg is based in Berlin, Germany and
[recognized as tax-exempt](https://codeberg.org/codeberg/org/src/Imprint.md#user-content-gemeinn%C3%BCtzigkeit-recognition-of-status-as-non-profit-ngo-recognition-as-tax-excempt-entity) by the German authorities.
[recognized as tax-exempt](https://codeberg.org/codeberg/org/src/Imprint.md#user-content-gemeinn%C3%BCtzigkeit-recognition-of-status-as-non-profit-ngo-recognition-as-tax-excempt-entity)
by the German authorities.
If you want to receive a receipt for your membership fee,
please write us to [codeberg-at-codeberg.org](mailto:codeberg-PLEASE-REMOVE-THIS-PART-FOR-SPAM-PROTECTION@codeberg.org).

19
content/improving-codeberg/index.md
View file

@ -30,22 +30,29 @@ This section has moved to a dedicated page. <a href="./donate" class="btn btn-pr
## Join Codeberg e.V.
If you're interested in committing even more to Codeberg, consider [joining Codeberg e.V.](https://join.codeberg.org), the non-profit association behind Codeberg.org.
If you're interested in committing even more to Codeberg, consider [joining Codeberg e.V.](https://join.codeberg.org),
the non-profit association behind Codeberg.org.
## Contribute to Codeberg
Do you have ideas on improving Codeberg? Have you found a bug and would like to report (or even fix) it? You're welcome to contribute to Codeberg!
Do you have ideas on improving Codeberg? Have you found a bug and would like to report (or even fix) it?
You're welcome to contribute to Codeberg!
We coordinate teams and efforts using our [dedicated Contrib tracker](https://codeberg.org/Codeberg/Contributing).
Head there to introduce yourself and find tasks that interest you.
You should also consider [Joining Codeberg](#join-codeberg-e.v.) where you'll get easier access to internal teams and task forces.
You should also consider [Joining Codeberg](#join-codeberg-e.v.) where you'll get easier access to internal teams and
task forces.
Last but not least, you can always [work on the Codeberg Docs](/improving-documentation/docs-contributor-faq)!
Codeberg explicitly welcomes newcomers or career changers to its repos, and we will gladly mentor you as resources permit.
If you have questions, always feel free to ask in the Issue Trackers or on the Matrix Channels mentioned on the [Contact page](/contact).
Even tiny patches or suggestions, even if you are not a skilled developer, will be considered and are part of the community-maintenance mission of Codeberg.
If you have questions, always feel free to ask in the Issue Trackers or on the Matrix Channels mentioned on the
[Contact page](/contact).
Even tiny patches or suggestions, even if you are not a skilled developer, will be considered and are part of the
community-maintenance mission of Codeberg.
## Reporting issues
If you experience an issue on some of the projects provided by Codeberg, please report it on Codeberg first so people can check if it's specific to Codeberg. See list of Codeberg projects below, with links to their repositories/issue trackers.
If you experience an issue on some of the projects provided by Codeberg, please report it on Codeberg first so people
can check if it's specific to Codeberg.
See list of Codeberg projects below, with links to their repositories/issue trackers.

26
content/improving-documentation/create-article.md
View file

@ -6,9 +6,13 @@ eleventyNavigation:
order: 10
---
To write a new article, create a new Markdown file next to the existing files in the section that you want to put your article in. So, if for example you want to create an article called "Keeping your repo clean with .gitignore" in the "Working with Git Repositories" section, put a new file called for example `gitignore.md` into the `content/git` directory. Please adhere to the [file naming conventions](/improving-documentation/docs-contributor-faq#how-should-files-be-named%3F).
To write a new article, create a new Markdown file next to the existing files in the section that you want to put your
article in. So, if for example you want to create an article called "Keeping your repo clean with .gitignore" in the
"Working with Git Repositories" section, put a new file called for example `gitignore.md` into the `content/git` directory.
Please adhere to the [file naming conventions](/improving-documentation/docs-contributor-faq#how-should-files-be-named%3F).
Then, add the `eleventyNavigation` header to your newly created file. That header contains information about the article's place in the structure of the site.
Then, add the `eleventyNavigation` header to your newly created file.
That header contains information about the article's place in the structure of the site.
It can look like this:
@ -28,19 +32,25 @@ Hello foo!
Hello bar!
```
Every section and article has a unique `key`. If `parent` is set to the `key` of another section, the current article will become a child of that other section.
Every section and article has a unique `key`. If `parent` is set to the `key` of another section, the current article
will become a child of that other section.
The other fields are `title` and `order`, where
- `title` is merely a display name and determines the menu entry label as well as the article's heading but has no other "technical" semantics and
- `order` is a number that can be used to enforce a specific order of articles (which is good for step-by-step guides such as Getting Started for example).
- `title` is merely a display name and determines the menu entry label as well as the article's heading but has no other
"technical" semantics and
- `order` is a number that can be used to enforce a specific order of articles (which is good for step-by-step guides
such as Getting Started for example).
So to create a new article, find the `key` of your desired parent section in its Markdown source code and use it as the `parent` for your new article.
So to create a new article, find the `key` of your desired parent section in its Markdown source code and use it as the
`parent` for your new article.
After the header is in place, you can now start writing your article in Markdown. It is recommended to add a blank line after the header's trailing three dashes.
After the header is in place, you can now start writing your article in Markdown. It is recommended to add a blank line
after the header's trailing three dashes.
{% admonition "warning" %}
Please do not repeat the article's title as a first-level heading in Markdown. It will added automatically when generating the final site.
Please do not repeat the article's title as a first-level heading in Markdown. It will added automatically when
generating the final site.
{% endadmonition %}

17
content/improving-documentation/docs-contributor-faq.md
View file

@ -6,7 +6,8 @@ eleventyNavigation:
order: 90
---
The intent of this document is to give answers to a number of questions that might arise when starting to contribute to Codeberg Documentation. If your question is not listed, feel free to [ask in the issue tracker](https://codeberg.org/Codeberg/Documentation/issues).
The intent of this document is to give answers to a number of questions that might arise when starting to contribute to
Codeberg Documentation. If your question is not listed, feel free to [ask in the issue tracker](https://codeberg.org/Codeberg/Documentation/issues).
### How should files be named?
@ -14,17 +15,23 @@ Please adhere to [kebab-Case](https://en.wikipedia.org/wiki/Kebab_case) naming r
### When is my contribution being approved?
A Pull Request to Codeberg/Documentation will be reviewed by at least one other Codeberg Documentation collaborators and if your Pull Request is approved, they will merge it into the main branch.
A Pull Request to Codeberg/Documentation will be reviewed by at least one other Codeberg Documentation collaborators and
if your Pull Request is approved, they will merge it into the main branch.
There are a number of exceptions to the rule above:
- For bugfixes and other small and non-controversial changes, the process is much simplified - here it is enough for one collaborator to green-light and merge the changes. If you're already a collaborator yourself, feel free to merge right away (after sufficient testing, that is).
- For bugfixes and other small and non-controversial changes, the process is much simplified - here it is enough for one
collaborator to green-light and merge the changes.
If you're already a collaborator yourself, feel free to merge right away (after sufficient testing, that is).
- For major changes, at least two people will need to approve the contribution.
- For changes that are critical, e.g. ones that might legally affect Codeberg e.V., the chairperson of Codeberg e.V. will need to approve of the changes as well.
- For changes that are critical, e.g. ones that might legally affect Codeberg e.V., the chairperson of Codeberg e.V.
will need to approve of the changes as well.
### How to link to non-existing articles? / Draft Articles
While it is not directly possible to link to non-existing articles, it is possible to create Draft Articles, which are articles that cannot be localized for example via the menu, but which do exist under their URL and do show a message stating that the article is unpublished.
While it is not directly possible to link to non-existing articles, it is possible to create Draft Articles,
which are articles that cannot be localized for example via the menu, but which do exist under their URL and do show a
message stating that the article is unpublished.
Creating such a draft article can be done by creating a new article with the
`draft` property set to true, like this:

10
content/improving-documentation/index.md
View file

@ -31,8 +31,12 @@ We're very happy you're considering to contribute to Codeberg Documentation!
### How do I contribute to Codeberg Documentation?
To contribute to Codeberg Documentation, the first thing you should do (if you haven't already done it) is to create your own fork of the [Codeberg/Documentation repository](https://codeberg.org/Codeberg/Documentation).
To contribute to Codeberg Documentation, the first thing you should do (if you haven't already done it) is to create
your own fork of the [Codeberg/Documentation repository](https://codeberg.org/Codeberg/Documentation).
Then, for each major contribution that you want to make (e.g. for each new article), create a new branch, make your contributions and finally make a Pull Request to the Codeberg/Documentation repository. You can find the source code to all articles in the `content` directory of Codeberg Documentation's source tree.
Then, for each major contribution that you want to make (e.g. for each new article), create a new branch, make your
contributions and finally make a Pull Request to the Codeberg/Documentation repository.
You can find the source code to all articles in the `content` directory of Codeberg Documentation's source tree.
The Codeberg Documentation collaborators will then review your pull request, they may request some changes and eventually, once all is good, they may merge your contribution into the official repository and deploy it to the live site.
The Codeberg Documentation collaborators will then review your pull request, they may request some changes and
eventually, once all is good, they may merge your contribution into the official repository and deploy it to the live site.

7
content/improving-documentation/preview.md
View file

@ -6,6 +6,9 @@ eleventyNavigation:
order: 15
---
Yes, but currently only if you're working with a local clone of the repository. In that case, simply follow the instructions in the [`README.md`](https://codeberg.org/Codeberg/Documentation/src/README.md) file to set up and run a local preview.
Yes, but currently only if you're working with a local clone of the repository. In that case, simply follow the
instructions in the [`README.md`](https://codeberg.org/Codeberg/Documentation/src/README.md) file to set up and run a
local preview.
It is recommended to set this up, because it can help you a lot in spotting errors that would otherwise go unnoticed, especially aesthetic errors and broken links.
It is recommended to set this up, because it can help you a lot in spotting errors that would otherwise go unnoticed,
especially aesthetic errors and broken links.

16
content/improving-documentation/screenshots.md
View file

@ -9,12 +9,18 @@ eleventyNavigation:
Screenshots for Codeberg Documentation should follow the guidelines explained in
[Kesi Parker's excellent article](https://medium.com/technical-writing-is-easy/screenshots-in-documentation-27b45342aad8).
They should be created using the "Knut" demo account on `codeberg-test.org`. If you're a regular, trusted contributor to Documentation, you can find its credentials in a private repository in the `knut` organization on `codeberg.org`.
They should be created using the "Knut" demo account on `codeberg-test.org`. If you're a regular, trusted contributor to
Documentation, you can find its credentials in a private repository in the `knut` organization on `codeberg.org`.
Otherwise, feel free to request screenshots being added when merging your PR. For that, please include `TODO SCREENSHOT [of foo]` in your article.
Otherwise, feel free to request screenshots being added when merging your PR. For that, please include
`TODO SCREENSHOT [of foo]` in your article.
On the technical side, screenshots should ideally be created in PNG and WebP or JPEG for photographs. Screenshots should be in a large enough resolution so that text is clearly readable and their filenames should follow Codeberg Documentation's [naming conventions](/improving-documentation/docs-contributor-faq#how-should-files-be-named%3F).
On the technical side, screenshots should ideally be created in PNG and WebP or JPEG for photographs.
Screenshots should be in a large enough resolution so that text is clearly readable and their filenames should follow
Codeberg Documentation's [naming conventions](/improving-documentation/docs-contributor-faq#how-should-files-be-named%3F).
Please put screenshots under `content/images/[section]/[article]/...` where `[section]` and `[article]` are the kebab-cased names of the section or your article, respectively.
Please put screenshots under `content/images/[section]/[article]/...` where `[section]` and `[article]` are the
kebab-cased names of the section or your article, respectively.
Codeberg Documentation encodes images to WebP, JPEG and PNG format on build time, in order to increase page loading speed and reduce traffic.
Codeberg Documentation encodes images to WebP, JPEG and PNG format on build time, in order to increase page loading
speed and reduce traffic.

56
content/improving-documentation/style-guide.md
View file

@ -5,21 +5,28 @@ eleventyNavigation:
parent: ImprovingTheDocumentation
---
The present style guide aims at streamlining the authoring process. We would like to maintain a consistent style to guarantee a pleasant reading experience. If you haven't done it already, please read the [Documentation Contributor FAQ](https://docs.codeberg.org/improving-codeberg/docs-contributor-faq/) before using this guide.
The present style guide aims at streamlining the authoring process.
We would like to maintain a consistent style to guarantee a pleasant reading experience.
If you haven't done it already, please read the [Documentation Contributor FAQ](https://docs.codeberg.org/improving-codeberg/docs-contributor-faq/)
before using this guide.
A style guide is meant to be used as a reference when there is a doubt about a style convention. Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects.
A style guide is meant to be used as a reference when there is a doubt about a style convention.
Think of it as a set of recommendations to avoid time-consuming discussions about grammar, typography, and layout aspects.
It is not a novel that we expect you to read from A to Z. For instance, if you want to know how to format date and numbers, you can head immediately to the relevant section under [Dates, times, and numbers](#dates%2C-times%2C-and-numbers).
It is not a novel that we expect you to read from A to Z. For instance, if you want to know how to format date and numbers,
you can head immediately to the relevant section under [Dates, times, and numbers](#dates%2C-times%2C-and-numbers).
In an ideal world, the reviewer is the person that must be in charge of enforcing the guidelines provided in the style guide.
{% admonition "info" "Note" %}
This style guide is a starting point. Feel free to create an issue, open a Pull Request, and modify it according to the community's needs.
This style guide is a starting point. Feel free to create an issue, open a Pull Request, and modify it according to the
community's needs.
{% endadmonition %}
We intend to reach people from different knowledge backgrounds and life experiences. Therefore, we kindly ask you to follow these rules:
We intend to reach people from different knowledge backgrounds and life experiences.
Therefore, we kindly ask you to follow these rules:
| Rule | What we recommend |
| :------------------------ | :-------------------------------------------------------------------------------------------- |
@ -55,9 +62,11 @@ Follow these guidelines to organize the structure of your document:
Screenshots and other images can heavily improve the quality of an article without much effort.
In our situation, screenshots generally help users find what they are looking for. They also use them to compare what _they_ are seeing with what the _article's author_ expects them to be seeing.
In our situation, screenshots generally help users find what they are looking for. They also use them to compare what
_they_ are seeing with what the _article's author_ expects them to be seeing.
However, readers that cannot see images (e.g. users depending on screen reader software) should not be prevented from reading your article.
However, readers that cannot see images (e.g. users depending on screen reader software) should not be prevented from
reading your article.
{% admonition "tip" %}
@ -65,7 +74,8 @@ Before including screenshots, we highly recommend writing articles in text first
{% endadmonition %}
- Use text to describe instructions (i.e. where does the reader need to click). Do not exclusively rely on visual cues (i.e. arrows, icons) in screenshots.
- Use text to describe instructions (i.e. where does the reader need to click). Do not exclusively rely on visual cues
(i.e. arrows, icons) in screenshots.
- When possible, use text to describe what you expect the reader to see after following an instruction or a set of instructions.
- When using images, always use an adequate amount of alt text.
@ -87,7 +97,8 @@ Wikipedia's Manual of Style contains [several good examples of alt text](https:/
- Do not use periods (.) and colons (:) at the end of your headings.
- Avoid using consecutive headings without any content in between.
- Avoid using abbreviations in the headings. This particularly applies to lesser known abbreviations.
- Use sentence-style capitalization, i.e. capitalize only the first letter of the first word in the heading as well as words where capitalization is compulsory, such as proper nouns.
- Use sentence-style capitalization, i.e. capitalize only the first letter of the first word in the heading as well as
words where capitalization is compulsory, such as proper nouns.
- Your headings must reflect the content of the text that follows.
- Begin your headings with the following parts of speech according to the typology of your content:
@ -105,13 +116,16 @@ By unordered lists, we mean **bullet-style** lists. Use unordered lists when the
- The input() function
- The len() function
By ordered lists, we mean **numbered** lists. Use ordered lists to describe procedures that involve multiple sequential steps, e.g.:
By ordered lists, we mean **numbered** lists. Use ordered lists to describe procedures that involve multiple sequential
steps, e.g.:
1. Type the URL into your browser's address bar
2. Press the Enter button
3. Go to the Login section and click on “Forgot Password”
Maintain a consistent punctuation style in lists. Decide whether you will use “complete sentences” or “sentence fragments” in your list items. Add a period (.) at the end of each list item if you choose to use complete sentences. Do not add a period at the end of each item if you are only using sentence fragments.
Maintain a consistent punctuation style in lists. Decide whether you will use “complete sentences” or “sentence fragments”
in your list items. Add a period (.) at the end of each list item if you choose to use complete sentences.
Do not add a period at the end of each item if you are only using sentence fragments.
### Straight and curly quotes
@ -187,19 +201,25 @@ Do not use hyphens for adjectives and adverbs ending in **-ly**, e.g.
## Document structure
If you write an excessively long article, your readers might get lost on the way. Break your article down in smaller articles for a better reading experience.
If you write an excessively long article, your readers might get lost on the way.
Break your article down in smaller articles for a better reading experience.
Avoid the excessive use of hyperlinks and cross-references within your document to prevent readers from being distracted.
### Sentences and paragraphs
A standard paragraph consists of three to eight sentences. If a paragraph exceeds the maximum allowed number of sentences, reorganize the information to enhance readability.
A standard paragraph consists of three to eight sentences. If a paragraph exceeds the maximum allowed number of sentences,
reorganize the information to enhance readability.
Favor “self-contained information units” over interconnected information units. An information unit is called self-contained when it does not depend on other information units to convey meaning. Interconnected information units make an excessive use of pronouns and conjunctions such as “this”, “it”, “consequently”, “therefore”, etc.
Favor “self-contained information units” over interconnected information units.
An information unit is called self-contained when it does not depend on other information units to convey meaning.
Interconnected information units make an excessive use of pronouns and conjunctions such as “this”, “it”, “consequently”,
“therefore”, etc.
### Notes and warnings
Keep notes and warnings outside the body of your running text. Use admonition boxes, also known as callouts, to show said information.
Keep notes and warnings outside the body of your running text. Use admonition boxes, also known as callouts, to show
said information.
The syntax is as follows:
@ -220,7 +240,8 @@ The following admonition types are currently available:
{% admonition "info" %}
Default type used should no type or an invalid one be provided. Should be used to give short and useful information to know about.
Default type used should no type or an invalid one be provided. Should be used to give short and useful information to
know about.
{% endadmonition %}
@ -250,7 +271,8 @@ Use to show and answer a question the user may ask in this situation.
### Topic typology
Adopt one of the following approaches according to the typology of your content (cf. the difference between “conceptual”, “procedural”, and “reference” content under the section [Headings](#headings)):
Adopt one of the following approaches according to the typology of your content
(cf. the difference between “conceptual”, “procedural”, and “reference” content under the section [Headings](#headings)):
| Content type | Recommended structure |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

6
content/integrations/index.md
View file

@ -8,8 +8,10 @@ eleventyNavigation:
These documentation pages contain information on how you can use third-party software with Codeberg.
Check out [delightful-forgejo](https://codeberg.org/forgejo-contrib/delightful-forgejo) to learn about the awesome ecosystem of Forgejo instances.
Can can also see [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/README.md), most of the Gitea-specific solutions should work with our Forgejo instance, too.
Check out [delightful-forgejo](https://codeberg.org/forgejo-contrib/delightful-forgejo) to learn about the awesome
ecosystem of Forgejo instances.
Can can also see [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/README.md), most of the Gitea-specific
solutions should work with our Forgejo instance, too.
{% assign navPages = collections.all | eleventyNavigation %}
{%- for entry in navPages %}

46
content/integrations/keycloak.md
View file

@ -5,7 +5,8 @@ eleventyNavigation:
parent: Integrations
---
This article will guide you through integrating Codeberg with Keycloak, allowing you to use Codeberg as an authentication provider.
This article will guide you through integrating Codeberg with Keycloak, allowing you to use Codeberg as an
authentication provider.
{% admonition "warning" %}
@ -13,7 +14,8 @@ Using Codeberg with Keycloak means that you explicitly trust Codeberg and its op
{% endadmonition %}
> To test configurations on your `localhost`, the `--hostname-url` flag can be used to change the _Redirect URI_ and other relevant fields' prefixes. The following example is not persistent between executions:
> To test configurations on your `localhost`, the `--hostname-url` flag can be used to change the _Redirect URI_ and
> other relevant fields' prefixes. The following example is not persistent between executions:
>
> ```shell data-line 2
> docker run -p 8080:8080 \
@ -26,36 +28,47 @@ Using Codeberg with Keycloak means that you explicitly trust Codeberg and its op
## Creating a new identity provider
From the Keycloak Administration UI, click on "Identity providers" and select "OpenID Connect v1.0" in the "User-defined" section.
From the Keycloak Administration UI, click on "Identity providers" and select "OpenID Connect v1.0" in the
"User-defined" section.
<img src="/images/integrations/keycloak/identity-providers.png" alt="Screenshot of the Identity Providers menu. The OpenID Connect v1.0 button is marked with a red box.">
<img
src="/images/integrations/keycloak/identity-providers.png"
alt="Screenshot of the Identity Providers menu. The OpenID Connect v1.0 button is marked with a red box.">
You should see a field called _Redirect URI_ that has already been filled out for you. Copy the link to your clipboard and leave the page open.
You should see a field called _Redirect URI_ that has already been filled out for you.
Copy the link to your clipboard and leave the page open.
<img src="/images/integrations/keycloak/redirect-uri.png" alt="Screenshot of the Redirect URI field.">
## Set up an OAuth2 application on Codeberg
On Codeberg, [go to "**Settings**", then "**Applications**"](https://codeberg.org/user/settings/applications). You should be able to find a section called _Manage OAuth2 Applications_.
On Codeberg, [go to "**Settings**", then "**Applications**"](https://codeberg.org/user/settings/applications).
You should be able to find a section called _Manage OAuth2 Applications_.
{% admonition "tip" %}
**Applications** can also be created under an **Organization** as opposed to being tied to one user's account:
<https://codeberg.org/org/YOUR_ORGANIZATION_NAME/settings/applications>.
Keycloak must be configured by the **Organization owner**. This approach can help increase the so-called [bus factor](https://en.wikipedia.org/wiki/Bus_factor), provided that multiple organization owners are present.
Keycloak must be configured by the **Organization owner**. This approach can help increase the so-called [bus factor](https://en.wikipedia.org/wiki/Bus_factor),
provided that multiple organization owners are present.
{% endadmonition %}
The _Application Name_ can be arbitrary; we will use "My Keycloak Instance" for illustrative purposes. Make sure to paste the _Redirect URI_ that was shown in Keycloak earlier.
The _Application Name_ can be arbitrary; we will use "My Keycloak Instance" for illustrative purposes.
Make sure to paste the _Redirect URI_ that was shown in Keycloak earlier.
<img src="/images/integrations/keycloak/manage-oauth2-applications.png" alt="Screenshot of Manage OAuth2 Applications section in Application settings on Codeberg.">
<img src="/images/integrations/keycloak/manage-oauth2-applications.png" alt="Screenshot of Manage OAuth2 Applications
section in Application settings on Codeberg.">
When you are done, click on the green _Create Application_ button.
You should now see two new fields: _Client ID_ and _Client Secret_.
<img src="/images/integrations/keycloak/new-oauth2-application.png" alt="Screenshot of the newly created application on Codeberg; it contains some generic information about the application, as well as the Client ID and Client Secret credentials.">
<img
src="/images/integrations/keycloak/new-oauth2-application.png"
alt="Screenshot of the newly created application on Codeberg; it contains some generic information about the application,
as well as the Client ID and Client Secret credentials.">
## Finish configuring Keycloak
@ -68,12 +81,17 @@ Let's finish configuring the OpenID Connect provider on Keycloak.
- **Client ID:** Use the Client ID provided by Codeberg.
- **Client Secret:** Use the Client Secret provided by Codeberg.
All other options can be left untouched. The [_discovery endpoint_](https://codeberg.org/.well-known/openid-configuration) will be used to fetch all metadata required for your Keycloak instance to work together with Codeberg.
All other options can be left untouched. The [_discovery endpoint_](https://codeberg.org/.well-known/openid-configuration)
will be used to fetch all metadata required for your Keycloak instance to work together with Codeberg.
You can also optionally enable the [_Proof Key for Code Exchange (PKCE)_](https://forgejo.org/docs/latest/user/oauth2-provider/#supported-oauth2-grants) extension in the _Show metadata_ dropdown menu.
You can also optionally enable the [_Proof Key for Code Exchange (PKCE)_](https://forgejo.org/docs/latest/user/oauth2-provider/#supported-oauth2-grants)
extension in the _Show metadata_ dropdown menu.
In summary, this is what your configuration should look like:
<img src="/images/integrations/keycloak/finish-keycloak-configuration.png" alt="Screenshot of the Identity provider configuration page; it contains all aforementioned configuration options.">
<img
src="/images/integrations/keycloak/finish-keycloak-configuration.png"
alt="Screenshot of the Identity provider configuration page; it contains all aforementioned configuration options.">
Click on the _Add_/_Save_ button. You will be redirected to the settings of your brand new identity provider. Now, you will be able to use Codeberg to authenticate with the services that you use Keycloak with. Enjoy!
Click on the _Add_/_Save_ button. You will be redirected to the settings of your brand new identity provider.
Now, you will be able to use Codeberg to authenticate with the services that you use Keycloak with. Enjoy!

47
content/integrations/liberapay.md
View file

@ -5,11 +5,14 @@ eleventyNavigation:
parent: Integrations
---
This article will guide you through integrating your Codeberg's projects with [Liberapay](https://liberapay.com), a platform that helps open-source developers receive donations.
This article will guide you through integrating your Codeberg's projects with [Liberapay](https://liberapay.com),
a platform that helps open-source developers receive donations.
After [signing up for an account](https://liberapay.com/sign-up) and setting up all the necessary financial information, you will be able to use **widgets**.
After [signing up for an account](https://liberapay.com/sign-up) and setting up all the necessary financial information,
you will be able to use **widgets**.
Widgets are small icons that can be used in places like Markdown documents. In the context of Liberapay, you can use widgets to:
Widgets are small icons that can be used in places like Markdown documents.
In the context of Liberapay, you can use widgets to:
- draw attention to the fact that you accept donations over Liberapay and that users can contribute to your project financially
- show how many people contribute to your project
@ -21,23 +24,33 @@ Widgets are small icons that can be used in places like Markdown documents. In t
2. Click on your profile picture on the top right of the page
3. A dropdown menu will appear. Click on **Widgets** button.
<img src="/images/integrations/liberapay/profile.png" alt="Screenshot of Liberapay's homepage with rectangles marking the profile picture on the top right of the page and the Widgets button.">
<img
src="/images/integrations/liberapay/profile.png"
alt="Screenshot of Liberapay's homepage with rectangles marking the profile picture on the top right of the page and
the Widgets button.">
After clicking on the **Widgets** button, you should be able to see a page full of the widgets that Liberapay provides!
<img src="/images/integrations/liberapay/widgets.png" alt="Screenshot of Liberapay's Widgets subpage. The first thing you should see is instructions on how you can add a Donation Button to your page, alongside with the HTML source code that you should use.">
<img
src="/images/integrations/liberapay/widgets.png"
alt="Screenshot of Liberapay's Widgets subpage. The first thing you should see is instructions on how you can add a
Donation Button to your page, alongside with the HTML source code that you should use.">
In order to embed a widget in a **Markdown document** using Markdown itself, we will take a few extra steps in the following section.
In order to embed a widget in a **Markdown document** using Markdown itself, we will take a few extra steps in the
following section.
## Modifying Liberapay widget for Markdown
{% admonition "Info" "Liberapay HTML code" %}
**Markdown documents** are not limited to repositories (such as `README.md` files). Codeberg is an instance of Forgejo, and Forgejo lets you use Markdown on README files, your profile's biography, as well as an organization's description.
**Markdown documents** are not limited to repositories (such as `README.md` files). Codeberg is an instance of Forgejo,
and Forgejo lets you use Markdown on README files, your profile's biography, as well as an organization's description.
{% endadmonition %}
In the following steps, we will show you how to convert the HTML code displayed on Liberapay's website into Markdown. As an example, we will use the **"Donation Button"** widget for the user `Codeberg`; make sure to replace `Codeberg` with your own username!
In the following steps, we will show you how to convert the HTML code displayed on Liberapay's website into Markdown.
As an example, we will use the **"Donation Button"** widget for the user `Codeberg`; make sure to replace `Codeberg`
with your own username!
The HTML code for the widget should look like this:
@ -60,7 +73,8 @@ Using these two URLs, we can embed that widget in Markdown format using the foll
[![LiberaPay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/Codeberg/donate)
```
Since this document is authored in Markdown (and rendered to HTML), we can just use that code to show how the final result will look like:
Since this document is authored in Markdown (and rendered to HTML), we can just use that code to show how the final
result will look like:
[![LiberaPay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/Codeberg/donate)
@ -74,9 +88,14 @@ By combining the two, we can embed an image and make it link to an external page
## Shields.io Badges
Liberapay also offers shields.io widgets, which are more dynamic than the simple "Donation Button" widget. They can be found at the bottom of the **Widgets** page.
Liberapay also offers shields.io widgets, which are more dynamic than the simple "Donation Button" widget.
They can be found at the bottom of the **Widgets** page.
<img src="/images/integrations/liberapay/shields_widgets.png" alt="List of the 4 Liberapay shields.io widgets, which can show the amount your projects receive weekly, your own weekly donations to other projects, the number of people donating to your projects, as well as a percentage showing how close you are to a weekly donation goal that you can set yourself.">
<img
src="/images/integrations/liberapay/shields_widgets.png"
alt="List of the 4 Liberapay shields.io widgets, which can show the amount your projects receive weekly, your own
weekly donations to other projects, the number of people donating to your projects, as well as a percentage showing how
close you are to a weekly donation goal that you can set yourself.">
{% admonition "Info" "shields.io Documentation" %}
@ -89,7 +108,8 @@ Liberapay also offers shields.io widgets, which are more dynamic than the simple
{% endadmonition %}
An example on including these badges in Markdown will follow. To use them, you will need to replace `{desired badge}` with one of the four options:
An example on including these badges in Markdown will follow. To use them, you will need to replace `{desired badge}`
with one of the four options:
- `gives`
- `goal`
@ -114,7 +134,8 @@ For clarity's sake, this is how the code for the `receives` widget should look l
## Embedding Liberapay badges in profiles and organizations
As mentioned before, it is currently possible to include Liberapay badges in profiles and organizations by embedding the Markdown code in descriptions.
As mentioned before, it is currently possible to include Liberapay badges in profiles and organizations by embedding the
Markdown code in descriptions.
### Profile Descriptions

28
content/integrations/matrix.md
View file

@ -5,23 +5,29 @@ eleventyNavigation:
parent: Integrations
---
This article will guide you through integrating Codeberg with Matrix, allowing repo updates to be automatically broadcast to your project's Matrix room.
This article will guide you through integrating Codeberg with Matrix, allowing repo updates to be automatically broadcast
to your project's Matrix room.
## Create a new Matrix account
To set up the Matrix integration, it is recommended that you [create a new account](https://app.element.io/#/register) dedicated to broadcasting your repo updates. This will act as a bot account. You can create an account on your preferred Matrix server.
To set up the Matrix integration, it is recommended that you [create a new account](https://app.element.io/#/register)
dedicated to broadcasting your repo updates. This will act as a bot account.
You can create an account on your preferred Matrix server.
## Getting an access token
You will need an access token to give Codeberg access to send updates from your dedicated Matrix account. Here's how to do it on the Element web client.
You will need an access token to give Codeberg access to send updates from your dedicated Matrix account.
Here's how to do it on the Element web client.
1. Log in to the [Element web client](https://app.element.io/) in a private/incognito browser window, with the Matrix account you created earlier.
1. Log in to the [Element web client](https://app.element.io/) in a private/incognito browser window, with the Matrix
account you created earlier.
2. Click on your account name in the top-left corner, then click on `All Settings` in the dropdown.
3. Optionally, you can set a display name and a profile picture for the account here.
4. Navigate to the `Help & About` tab on the left.
5. Scroll to the bottom and click on the `Access Token` dropdown in the advanced section.
6. Copy the access token that appears to a safe place.
7. **Do not log out of Element.** This will invalidate your access token. Instead, you can simply close your private/incognito browser.
7. **Do not log out of Element.** This will invalidate your access token.
Instead, you can simply close your private/incognito browser.
{% admonition "tip" %}
@ -41,8 +47,12 @@ Now we will connect the Matrix bot to your Codeberg repository. You will need ad
4. Here are explanations for some key fields:
- Homeserver URL: for example `https://matrix.org`
- Room ID: for example `!VTjWrzxSWgLJnHgDUd:matrix.org`. You can find this on Element in the `Advanced` tab for the room settings.
- Access token: type `Bearer <your_access_token>`. The access token is the [one you got earlier](#getting-an-access-token).
- Message type: `m.text` is the most basic type of plaintext message, whereas `m.notice` is intended for bots and [behaves slightly differently](https://spec.matrix.org/latest/client-server-api/#mnotice).
- Room ID: for example `!VTjWrzxSWgLJnHgDUd:matrix.org`.
You can find this on Element in the `Advanced` tab for the room settings.
- Access token: type `Bearer <your_access_token>`.
The access token is the [one you got earlier](#getting-an-access-token).
- Message type: `m.text` is the most basic type of plaintext message, whereas `m.notice` is intended for bots and
[behaves slightly differently](https://spec.matrix.org/latest/client-server-api/#mnotice).
Add your webhook, then click on the webhook URL. At the bottom now, there will be a `Test Delivery` button. Click this, and you will receive a message on your Matrix room!
Add your webhook, then click on the webhook URL. At the bottom now, there will be a `Test Delivery` button.
Click this, and you will receive a message on your Matrix room!

66
content/integrations/read-the-docs.md
View file

@ -5,7 +5,9 @@ eleventyNavigation:
parent: Integrations
---
This article will guide you through integrating Codeberg with [Read the Docs](https://readthedocs.org/) to allow automatic build of your documentation. It will show you how to connect Read the Docs to a Git repository hosted on Codeberg. To learn how Read the Docs works, take a look at the [official Documentation](https://docs.readthedocs.io).
This article will guide you through integrating Codeberg with [Read the Docs](https://readthedocs.org/) to allow
automatic build of your documentation. It will show you how to connect Read the Docs to a Git repository hosted on Codeberg.
To learn how Read the Docs works, take a look at the [official Documentation](https://docs.readthedocs.io).
{% admonition "warning" %}
@ -24,46 +26,60 @@ After sign-up you need to login with your user to access your [dashboard](https:
This steps shows how to create a new project on Read the Docs
1. On the [Read the Docs dashboard](https://readthedocs.org/dashboard/) click "Import a Project"
2. If you have connected Read the Docs with some provider e.g. GitHub, you see a list of your repos at that provider. Ignore it and click "Import Manually". You should see this screen:
2. If you have connected Read the Docs with some provider e.g. GitHub, you see a list of your repos at that provider.
Ignore it and click "Import Manually". You should see this screen:
<img src="/images/integrations/read-the-docs/import-manual.png" alt="Image of the Import Manual page">
<img src="/images/integrations/read-the-docs/import-manual.png" alt="Image of the Import Manual page">
1. Under "Name" enter the name of your project. Under "Repository URL" enter the Git URL of your repo. It has the form `https://codeberg.org/<owner>/<repo>.git`. Leave the rest as it is and click "Next"
2. You should now be on your Project page and see a warning that the project doesn't have a valid Webhook. Ignore that. Go to Admin->Integrations. You should see this screen:
3. Under "Name" enter the name of your project. Under "Repository URL" enter the Git URL of your repo.
It has the form `https://codeberg.org/<owner>/<repo>.git`. Leave the rest as it is and click "Next"
4. You should now be on your Project page and see a warning that the project doesn't have a valid Webhook. Ignore that.
Go to Admin->Integrations. You should see this screen:
<img src="/images/integrations/read-the-docs/admin-integrations.png" alt="Image of an admin website of a Read the docs project.
The integrations section of the admin page is selected.
The content of the Integrations sections states, that 'No integrations are currently configured.'.
An error message is shown in red saying that the project does not have a valid webhook set up.">
<img
src="/images/integrations/read-the-docs/admin-integrations.png"
alt="Image of an admin website of a Read the docs project.
The integrations section of the admin page is selected.
The content of the Integrations sections states, that 'No integrations are currently configured.'.
An error message is shown in red saying that the project does not have a valid webhook set up.">
5. Now click on "Add Integration" and select "GitHub incoming webhook" as type. You should see this screen:
<img src="/images/integrations/read-the-docs/github-integration.png" alt="Image of an admin website of a Read the docs project.
The integrations section of the admin page is selected.
The page content start with a header saying 'Integration - GitHub incoming webhook'.
After some explaining text an url specific to the Read the docs project is shown which can be used to manually configure this webhook.
The url shown is marked with a red border.">
<img
src="/images/integrations/read-the-docs/github-integration.png"
alt="Image of an admin website of a Read the docs project.
The integrations section of the admin page is selected.
The page content start with a header saying 'Integration - GitHub incoming webhook'.
After some explaining text an url specific to the Read the docs project is shown which can be used to manually
configure this webhook.
The url shown is marked with a red border.">
6. Copy the URL that is marked Red in the Image. You should keep it secret, as it allows pushing to your Documentation
7. Now go to the "Webhooks" Section of the settings of your Codeberg Repo. Create a new "Forgejo" Webhook
6. Copy the URL that is marked Red in the Image. You should keep it secret, as it allows pushing to your Documentation.
7. Now go to the "Webhooks" Section of the settings of your Codeberg Repo. Create a new "Forgejo" Webhook.
<img src="/images/integrations/read-the-docs/forgejo-webhook.png" alt="Image of a Forgejo repository configuration.
The tab 'Webhooks' is selected.
The button 'Add Webhook' has been clicked and presents a list of possible Webhooks integrations.
The 'Forgejo' entry in the list has been marked with a red border.">
<img
src="/images/integrations/read-the-docs/forgejo-webhook.png"
alt="Image of a Forgejo repository configuration.
The tab 'Webhooks' is selected.
The button 'Add Webhook' has been clicked and presents a list of possible Webhooks integrations.
The 'Forgejo' entry in the list has been marked with a red border.">
8. Under "Target URL" enter the URL you copied from the Read the Docs webhook
9. Under "Trigger On:" select "All Events"
<img src="/images/integrations/read-the-docs/add-webhook.png" alt="Image of the Forgejo 'Add Webhook' dialog.
The input field for 'Target URL' is marked with a red border.
Also the 'All Events' checkout below the 'Trigger On' section is marked with a red border.">
<img
src="/images/integrations/read-the-docs/add-webhook.png"
alt="Image of the Forgejo 'Add Webhook' dialog.
The input field for 'Target URL' is marked with a red border.
Also the 'All Events' checkout below the 'Trigger On' section is marked with a red border.">
Congratulation! Your done! To test it, push a commit in your Codeberg Repo and see if the documentation rebuilds. This may take a few minutes.
Congratulation! Your done! To test it, push a commit in your Codeberg Repo and see if the documentation rebuilds.
This may take a few minutes.
## Migrate Project
You may migrate a repository that is connected to Read the Docs from another Git forge to Codeberg. In this case, follow these steps:
You may migrate a repository that is connected to Read the Docs from another Git forge to Codeberg.
In this case, follow these steps:
1. Go to Admin->Settings of your Project on Read the Docs
2. Under "Repository URL" enter the Git URL of your Codeberg Repo

3
content/markdown/index.md
View file

@ -10,7 +10,8 @@ In these docs, you will learn how to use Markdown in issues, files and articles
The Codeberg platform (based on [Forgejo](https://forgejo.org/)) uses Markdown as the markup language for text formatting.
Forgejo uses [Goldmark](https://github.com/yuin/goldmark) as the rendering engine which is compliant with [CommonMark 0.30](https://spec.commonmark.org/0.30/).
The documentation of Codeberg is rendered using [markdown-it](https://github.com/markdown-it/markdown-it) which also supports CommonMark.
The documentation of Codeberg is rendered using [markdown-it](https://github.com/markdown-it/markdown-it) which also
supports CommonMark.
## Further reading

20
content/markdown/introduction-to-markdown.md
View file

@ -14,7 +14,8 @@ You can also use Markdown in many parts of Codeberg (Issues, Pull Requests, etc.
To write a Markdown file, simply create a new file, and edit it with a text editor of your choice.
Markdown doesn't consider single line breaks as the start of a new paragraph.
You can write all your text into one long line or introduce a new line every once in a while.
It is common practice to introduce a new line at around 80 characters to enable users to easily read the plain un-rendered version of the Markdown file.
It is common practice to introduce a new line at around 80 characters to enable users to easily read the plain
un-rendered version of the Markdown file.
However, it's recommended to make a line break in Markdown when it makes sense, e.g. at the end of a sentence.
It makes diffs easier to understand, as the context of the complete sentence is preserved.
@ -83,17 +84,28 @@ This is also _italic text_.
Text may contain references to emoticons which are rendered as a small image, similar to an emoji.
You can render these by typing the name of the emoticon you want to use, surrounded by colons (`:`), like this `:codeberg:`.
Some examples are `:codeberg:` which is rendered as <img src="https://codeberg.org/assets/img/emoji/codeberg.png" class="codeberg-design" style="border-style:none;width:1em;height:1em" alt="The Codeberg mountain" /> and `:forgejo:` which is rendered as <img src="https://codeberg.org/assets/img/emoji/forgejo.png" class="codeberg-design" style="border-style:none;height:1em;width=1em" alt="The forgejo f letter" />.
Some examples are `:codeberg:` which is rendered as
<img
src="https://codeberg.org/assets/img/emoji/codeberg.png"
class="codeberg-design" style="border-style:none;width:1em;height:1em"
alt="The Codeberg mountain" />
and `:forgejo:` which is rendered as
<img
src="https://codeberg.org/assets/img/emoji/forgejo.png"
class="codeberg-design" style="border-style:none;height:1em;width=1em"
alt="The forgejo f letter" />.
### Referencing issues and pull requests
Issues and pull requests in Codeberg/Forgejo can be referenced in the comments of an issue or a pull request by using a hash `#` followed by the number of the issue or pull request.
Issues and pull requests in Codeberg/Forgejo can be referenced in the comments of an issue or a pull request by using a
hash `#` followed by the number of the issue or pull request.
The renderer will then include a link to the referenced issue into the comment.
After that, a link to the comment containing the reference will be added to the issues referenced in this way.
### Checkboxes
You can add checkboxes to comments by using a space surrounded by square brackets `[ ]`. These can be checked/unchecked later without editing the comment.
You can add checkboxes to comments by using a space surrounded by square brackets `[ ]`. These can be checked/unchecked
later without editing the comment.
This can for example be useful when creating a Todo list.
### Mermaid diagrams

3
content/markdown/preformatted-text.md
View file

@ -15,7 +15,8 @@ There are two ways to use monospace preformatted text within your Markdown docum
You can preformat a section of text or code by indenting the code with 4 or more spaces, or a tab.
Using indentation, it's not possible to add a rendering hint. It's also not possible to preformat text within a line using this syntax.
Using indentation, it's not possible to add a rendering hint. It's also not possible to preformat text within a line
using this syntax.
Indentation-based preformatting sometimes causes false positives where text is
preformatted that isn't supposed to. For this reason, it is disabled in some

3
content/markdown/using-images.md
View file

@ -8,7 +8,8 @@ eleventyNavigation:
It is possible to include images into the rendered form of a Markdown file.
Please refer to the [article on Screenshots](/improving-documentation/screenshots/) to learn how to use and include images in the Codeberg documentation.
Please refer to the [article on Screenshots](/improving-documentation/screenshots/) to learn how to use and include
images in the Codeberg documentation.
The syntax of including images is similar to the syntax of links.

2
content/markdown/using-links.md
View file

@ -31,7 +31,7 @@ Gets rendered as:
To add a link using the URL within your text use `<` and `>` to mark the link.
For example, if you want to add a link to `https://codeberg.org/`, add `<https://codeberg.org>` to your
text. This will render as <https://codeberg.org/>.
You can also just add the link to your text normally to have the same effect: https://codeberg.org.
You can also just add the link to your text normally to have the same effect: <https://codeberg.org>.
However it is easier to navigate to links if they are explicitly marked by the less than `<` and greater than `>` characters.
## URIs and URLs

50
content/security/2fa.md
View file

@ -8,9 +8,11 @@ eleventyNavigation:
## Why two-factor authentication?
While it is important to have a strong password for extra security, it is a good idea to configure two-factor authentication for your account in case your password or device ever gets compromised.
While it is important to have a strong password for extra security, it is a good idea to configure two-factor
authentication for your account in case your password or device ever gets compromised.
With two-factor authentication, you will be asked for an authentication code generated using your phone in addition to your password when logging into Codeberg.
With two-factor authentication, you will be asked for an authentication code generated using your phone in addition to
your password when logging into Codeberg.
That way, your account cannot be compromised even if your password gets compromised, as long as your phone stays safe.
@ -22,8 +24,10 @@ That way, your account cannot be compromised even if your password gets compromi
You will need an authenticator app installed on your phone.
If you don't already have an authenticator app and you're not sure which app to use, have a look at Aegis Authenticator
([F-Droid](https://f-droid.org/de/packages/com.beemdevelopment.aegis/) | [Google Play Store](https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis&hl=en_US)) or Authenticator ([App Store](https://itunes.apple.com/app/authenticator/id766157276)).
If you don't already have an authenticator app and you're not sure which app to use, have a look at
Aegis Authenticator ([F-Droid](https://f-droid.org/de/packages/com.beemdevelopment.aegis/) |
[Google Play Store](https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis&hl=en_US))
or Authenticator ([App Store](https://itunes.apple.com/app/authenticator/id766157276)).
#### Step 1: Navigate to your user settings
@ -37,7 +41,8 @@ If you don't already have an authenticator app and you're not sure which app to
<img src="/images/security/2fa/qr-scan.jpg" alt="Scanning QR Code">
After scanning the QR code with your app, enter the six-digit code displayed in your app into the "Passcode" field of the settings form, then click "Verify".
After scanning the QR code with your app, enter the six-digit code displayed in your app into the "Passcode" field of
the settings form, then click "Verify".
#### Step 4: Store your scratch token in a safe place
@ -53,13 +58,17 @@ Please store this token in a safe place.
That's it - you have now configured two-factor authentication for your account.
From now on, each time you log into Codeberg you will be asked for an authentication code from your app, adding an extra layer of security over just using a password.
From now on, each time you log into Codeberg you will be asked for an authentication code from your app, adding an extra
layer of security over just using a password.
### WebAuthn
If TOTP is configured, you can also add security keys to your account. These security keys are hardware devices that securely store cryptographic keys. They are either integrated on your device, like some phones' fingerprint scanners, or connect to it via USB or NFC.
If TOTP is configured, you can also add security keys to your account. These security keys are hardware devices that
securely store cryptographic keys.
They are either integrated on your device, like some phones' fingerprint scanners, or connect to it via USB or NFC.
While you'll be able to recover access to your account using TOTP if your key breaks, if you can, you should add at least 2 security keys.
While you'll be able to recover access to your account using TOTP if your key breaks, if you can, you should add at
least 2 security keys.
#### Step 1: Navigate to your user settings
@ -87,13 +96,16 @@ WebAuthn is now configured for your account! Now, when you sign in, you'll be gi
{% admonition "Tip" %}
You can very likely use your WebAuthn security key to secure your SSH key, learn more about this on (Adding an SSH key to your account)[/security/ssh-key]).
You can very likely use your WebAuthn security key to secure your SSH key, learn more about this on
(Adding an SSH key to your account)[/security/ssh-key]).
{% endadmonition %}
## Personal access token
If you push to Codeberg via HTTP (see [Clone & Commit via HTTP](/git/clone-commit-via-http)), an extra step will be needed to create a personal access token. This token will replace your normal password (+ authentication code) on Codeberg.
If you push to Codeberg via HTTP (see [Clone & Commit via HTTP](/git/clone-commit-via-http)),
an extra step will be needed to create a personal access token.
This token will replace your normal password (+ authentication code) on Codeberg.
In your profile settings on Codeberg, go to the `Applications` tab.
In the section `Manage Access Tokens`, add a `Token Name` and confirm by clicking on `Generate Token`.
@ -106,14 +118,16 @@ Make sure you keep the generated token in a safe place, because it will not be s
When asked for your password, just enter the token.
You can create as many tokens as you'd like: one for each computer, one for each Git client, one for each session... you decide! You can also revoke tokens at any time by pressing `Delete` next to the token (see previous screenshot).
You can create as many tokens as you'd like: one for each computer, one for each Git client, one for each session...
you decide! You can also revoke tokens at any time by pressing `Delete` next to the token (see previous screenshot).
## Configure Git with 2FA
If you want to clone a repository using the Git CLI and 2FA enabled, you have two choices:
- use `SSH`: you do not have to do any special configuration, just use your ssh_key to login
- use `HTTPS`: for the login you use your username and your generated access token as a password. First time you enter it, it will be saved for your repository.
- use `HTTPS`: for the login you use your username and your generated access token as a password.
First time you enter it, it will be saved for your repository.
<pre>
$ git clone https://codeberg.org/username/repo.git
@ -121,7 +135,8 @@ Username for 'https://codeberg.org': username
Password for 'https://username@codeberg.org': access-token
</pre>
If you want to permanently save your generated access token you can use the following command to store it globally on your computer:
If you want to permanently save your generated access token you can use the following command to store it globally on
your computer:
```
git config --global credential.helper cache
@ -129,7 +144,9 @@ git config --global credential.helper cache
## Troubleshooting
Codeberg's instance of Forgejo is using an [OTP library](https://github.com/pquerna/otp/) to generate 2FA tokens and follows the [RFC 6238 standard](https://datatracker.ietf.org/doc/html/rfc6238) to generate TOTP which uses 30 seconds long time frames to accept your 2FA code.
Codeberg's instance of Forgejo is using an [OTP library](https://github.com/pquerna/otp/) to generate 2FA tokens and
follows the [RFC 6238 standard](https://datatracker.ietf.org/doc/html/rfc6238) to generate TOTP which uses 30 seconds
long time frames to accept your 2FA code.
```
00:00 00:30 01:00
@ -139,4 +156,7 @@ Codeberg's instance of Forgejo is using an [OTP library](https://github.com/pque
Previous Current Next
```
Codeberg's server is always at the **Current** period. If a token of the **Previous** period is submitted, which was generated between 00:00-00:30, it will be accepted, as long as that token was submitted between 00:30-01:00. So at a minimum you always got 30 seconds to submit the token, before it becomes "invalid" and Codeberg always accept two codes (**Previous**, **Current**)
Codeberg's server is always at the **Current** period. If a token of the **Previous** period is submitted, which was
generated between 00:00-00:30, it will be accepted, as long as that token was submitted between 00:30-01:00.
So at a minimum you always got 30 seconds to submit the token, before it becomes "invalid" and Codeberg always accept
two codes (**Previous**, **Current**)

55
content/security/gpg-key.md
View file

@ -8,22 +8,25 @@ eleventyNavigation:
## What is a GPG keypair?
GPG is an open-source cryptographic software application that implements the [OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) standard. With a GPG keypair, you can sign or encrypt text. Git allows you to sign your commits, so other collaborators can be assured it was you who created them.
GPG is an open-source cryptographic software application that implements the
[OpenPGP](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) standard.
With a GPG keypair, you can sign or encrypt text.
Git allows you to sign your commits, so other collaborators can be assured it was you who created them.
## Checking for an Existing GPG keypair
If you have your public key in an easy-to-find location, great! You can skip to [adding it to your account](#adding-your-public-gpg-key-to-codeberg). If not, we will be using the [GnuPG software](https://gnupg.org/download/index.html#binary) to check.
If you have your public key in an easy-to-find location, great! You can skip to [adding it to your account](#adding-your-public-gpg-key-to-codeberg).
If not, we will be using the [GnuPG software](https://gnupg.org/download/index.html#binary) to check.
1. Download and install [GnuPG](https://gnupg.org/download/index.html#binary).
{% admonition "tip" %}
If you are using Linux, this might already be installed. Check by typing `gpg --version` in the terminal.
{% endadmonition %}
2. Type `gpg --list-secret-keys --keyid-format LONG` into your terminal, and it will list all the keys that you have both a public and a private key for.
3. Look through the output for a key you want. Continue to [Generating a GPG key](#generating-a-gpg-keypair) if there are none, or if there are none that you want to use. If you wish to use one, go to [adding your GPG key to Codeberg](#adding-your-public-gpg-key-to-codeberg).
{% admonition "tip" %}
If you are using Linux, this might already be installed. Check by typing `gpg --version` in the terminal.
{% endadmonition %}
2. Type `gpg --list-secret-keys --keyid-format LONG` into your terminal, and it will list all the keys that you have
both a public and a private key for.
3. Look through the output for a key you want. Continue to [Generating a GPG key](#generating-a-gpg-keypair) if there
are none, or if there are none that you want to use.
If you wish to use one, go to [adding your GPG key to Codeberg](#adding-your-public-gpg-key-to-codeberg).
{% admonition "warning" %}
@ -33,30 +36,33 @@ Make sure that your selected key uses the same email as your Codeberg account.
## Generating a GPG keypair
If you haven’t already, be sure to [install](https://gnupg.org/download/index.html#binary) GnuPG, as you will be using it to generate your keys.
If you haven’t already, be sure to [install](https://gnupg.org/download/index.html#binary) GnuPG, as you will be using
it to generate your keys.
1. Type `gpg --full-generate-key` into your terminal.
2. Type `1` and press Enter to select `RSA and RSA`.
3. Enter your desired key size; we recommend 4096 bits. Press Enter to confirm.
4. Choose the amount of time you want it to be valid for; we recommend 1-2 years for increased security, but you can type 0 if you don't want it expire. Press Enter to confirm.
4. Choose the amount of time you want it to be valid for; we recommend 1-2 years for increased security, but you can
type 0 if you don't want it expire. Press Enter to confirm.
5. Verify your selections are correct, then type `y` and press Enter to confirm.
6. Enter your information; be sure to use the same email as your Codeberg account.
7. Type in a passphrase; make sure you write it down somewhere safe. You'll need it later to add your key to Git or revoke it if it's compromised.
7. Type in a passphrase; make sure you write it down somewhere safe. You'll need it later to add your key to Git or
revoke it if it's compromised.
## Adding your public GPG key to Codeberg
1. Type `gpg --list-secret-keys --keyid-format LONG` into the terminal.
2. Select the key you would like to use (most likely the one you just generated). In this example, the GPG key ID is `3AA5C34371567BD2`:
```shell
$ gpg --list-secret-keys --keyid-format LONG
/home/knut/.gnupg/pubring.kbx
--------------------------
sec rsa4096/3AA5C34371567BD2 2021-06-06 [SC] [expires: 2022-06-06]
6CD8F2B4F3E2E8F08274B563480F8962730149C7
uid [ultimate] knut <knut@codeberg.org>
ssb rsa4096/42B317FD4BA89E7A 2021-06-06 [E] [expires: 2022-06-06]
```
```shell
$ gpg --list-secret-keys --keyid-format LONG
/home/knut/.gnupg/pubring.kbx
--------------------------
sec rsa4096/3AA5C34371567BD2 2021-06-06 [SC] [expires: 2022-06-06]
6CD8F2B4F3E2E8F08274B563480F8962730149C7
uid [ultimate] knut <knut@codeberg.org>
ssb rsa4096/42B317FD4BA89E7A 2021-06-06 [E] [expires: 2022-06-06]
```
3. Type `gpg --armor --export <GPG KEY ID>` into the terminal. This will output your public key.
4. Copy the output beginning with `-----BEGIN PGP PUBLIC KEY BLOCK-----` and ending with `-----END PGP PUBLIC KEY BLOCK-----`.
@ -66,7 +72,8 @@ ssb rsa4096/42B317FD4BA89E7A 2021-06-06 [E] [expires: 2022-06-06]
## Verifying your public GPG key
Anyone can add a random public key; but fortunately, Codeberg provides a mechanism to verify that the key belongs to you.
Every keypair consists of a public and a private key that are connected to one another. Using this private key, you can sign the provided message. If the signed message is valid, Codeberg can confirm that the added key is yours.
Every keypair consists of a public and a private key that are connected to one another. Using this private key,
you can sign the provided message. If the signed message is valid, Codeberg can confirm that the added key is yours.
1. Go to the [SSH/GPG Keys tab](https://codeberg.org/user/settings/keys) in your Codeberg settings.
2. Click on the **Verify** button by the GPG key you would like to verify.

59
content/security/ssh-key.md
View file

@ -6,7 +6,8 @@ eleventyNavigation:
order: 20
---
It is recommended to use one key per client. This means that if you access your Codeberg repository from your home PC, your laptop and your office PC you should generate separate keys for each machine.
It is recommended to use one key per client. This means that if you access your Codeberg repository from your home PC,
your laptop and your office PC you should generate separate keys for each machine.
## Generating an SSH key pair
@ -25,7 +26,8 @@ It is recommended to use one key per client. This means that if you access your
> Generating public/private ed25519 key pair.
```
3. When you're prompted to "Enter a file in which to save the key", press <kbd>Enter</kbd>. This accepts the default file location:
3. When you're prompted to "Enter a file in which to save the key", press <kbd>Enter</kbd>.
This accepts the default file location:
```shell
> Enter file in which to save the key (/home/knut/.ssh/id_ed25519): [Press enter]
@ -41,11 +43,14 @@ It is recommended to use one key per client. This means that if you access your
ssh-keygen -t ed25519 -a 100
```
3. This time, enter a new filepath when prompted (e.g., `~/.ssh/id_ed25519_codeberg`) to avoid overwriting the existing key.
3. This time, enter a new filepath when prompted (e.g., `~/.ssh/id_ed25519_codeberg`) to avoid overwriting the
existing key.
4. You will be asked for a passphrase; enter one if you'd like, or leave the prompt empty.
Your private key can be protected by a passphrase. This adds a layer of authentication that increases security. Be aware that this will only be helpful for certain attack scenarios and does not offer 100% protection. It is recommended to keep your private key safe and - well - private.
Your private key can be protected by a passphrase. This adds a layer of authentication that increases security.
Be aware that this will only be helpful for certain attack scenarios and does not offer 100% protection.
It is recommended to keep your private key safe and - well - private.
### FIDO2 with OpenSSH
@ -59,15 +64,18 @@ Your private key can be protected by a passphrase. This adds a layer of authenti
3. If you have set one on your key, you'll be prompted for your FIDO2 PIN. Enter it to continue
4. When you're prompted to "Enter a file in which to save the key", press <kbd>Enter</kbd>. This accepts the default file location.
4. When you're prompted to "Enter a file in which to save the key", press <kbd>Enter</kbd>.
This accepts the default file location.
5. You will be asked for a passphrase; enter one if you'd like, or leave the prompt empty.
Keep in mind that now, every time you wish to use Codeberg over SSH, you must have your security key plugged in and will be prompted to touch it to continue.
Keep in mind that now, every time you wish to use Codeberg over SSH, you must have your security key plugged in and will
be prompted to touch it to continue.
## Add the SSH key to Codeberg
1. Copy the SSH key to your clipboard. You must only copy the public key not the private one. You can identify it by the `.pub` suffix. By default, you can find the public key in `$HOME/.ssh/id_ed25519.pub`.
1. Copy the SSH key to your clipboard. You must only copy the public key not the private one. You can identify it by the
`.pub` suffix. By default, you can find the public key in `$HOME/.ssh/id_ed25519.pub`.
On Linux you can use `xclip` on the command line. You may need to install it from your package manager.
@ -89,21 +97,23 @@ Keep in mind that now, every time you wish to use Codeberg over SSH, you must ha
These commands will copy the contents of id_ed25519.pub (your SSH public key) to your clipboard.
> Alternatively you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to your clipboard.
> Alternatively you can locate the hidden .ssh folder, open the file in your favorite text editor, and copy it to
> your clipboard.
2. Navigate to your user settings
<img src="/images/security/user-settings.png" alt="User Settings">
<img src="/images/security/user-settings.png" alt="User Settings">
3. Go to the section **SSH / GPG Keys** and click on **Add key**.
<img src="/images/security/ssh-key/add-ssh-key.png" alt="SSH Key Settings">
<img src="/images/security/ssh-key/add-ssh-key.png" alt="SSH Key Settings">
4. Give an appropriate name for the key.
5. Paste your key string into **Content** field.
6. Click the **Add key** button.
> You can always access your SSH public keys from `https://codeberg.org/username.keys`, substituting in your Codeberg username.
> You can always access your SSH public keys from `https://codeberg.org/username.keys`, substituting in your Codeberg
> username.
## Test the SSH connection
@ -129,16 +139,22 @@ Hi there, ____! You've successfully authenticated with the key named ____, but F
If this is unexpected, please log in with password and setup Forgejo under another user.
```
_Note: All Codeberg users share a single Unix user named `git` which is used to check out repositories. Depending on the key provided, permission is granted or denied. You can check out all repositories with your key which you have permission for. You can push code to all repositories where you have write access._
_Note: All Codeberg users share a single Unix user named `git` which is used to check out repositories._
_Depending on the key provided, permission is granted or denied._
_You can check out all repositories with your key which you have permission for._
_You can push code to all repositories where you have write access._
## Verifying your SSH Key
Anyone can add a random SSH key; but fortunately, Codeberg provides a mechanism to verify that the key belongs to you.
Every keypair consists of a public and a private key that are connected to one another. Using this private key, you can sign the provided message. If the signed message is valid, Codeberg can confirm that the added key is yours.
Every keypair consists of a public and a private key that are connected to one another.
Using this private key, you can sign the provided message. If the signed message is valid, Codeberg can confirm that the
added key is yours.
1. Go to the [SSH/GPG Keys tab](https://codeberg.org/user/settings/keys) in your Codeberg settings.
2. Click on the **Verify** button next to the SSH key you would like to verify.
3. Codeberg will show a token. Under its text box copy the command, and replace `/path_to_your_private_key` with the correct path of your private key.
3. Codeberg will show a token. Under its text box copy the command, and replace `/path_to_your_private_key` with the
correct path of your private key.
4. Copy the output, beginning with `-----BEGIN SSH SIGNATURE-----` and ending with `-----END SSH SIGNATURE-----`.
5. Paste it into the large textbox and click the **Verify** button.
@ -148,18 +164,21 @@ SSH can also be used to sign commits as an alternative for GPG. You can read mor
{% admonition "note" %}
SSH commit signing is available in Git 2.34 or later. To update your version of Git, see the [Git](https://git-scm.com/downloads) website.
SSH commit signing is available in Git 2.34 or later.
To update your version of Git,see the [Git](https://git-scm.com/downloads) website.
{% endadmonition %}
1. Open your terminal.
2. Type `git config --global gpg.format ssh`.
3. Type `git config --global user.signingKey <PATH TO PUBLIC SSH KEY>`, substituting `<PATH TO PUBLIC SSH KEY>` with the path to the public key you'd like to use, for example _~/.ssh/id_ed25519.pub_.
3. Type `git config --global user.signingKey <PATH TO PUBLIC SSH KEY>`, substituting `<PATH TO PUBLIC SSH KEY>` with the
path to the public key you'd like to use, for example _~/.ssh/id_ed25519.pub_.
4. Type `git config --global commit.gpgSign true`.
## Avoid re-typing the passphrase
Assuming you've created a secure key with a passphrase, SSH will prompt you for your passphrase for every connection. Common desktop environments like macOS or GNOME will offer you to cache your passphrase via an SSH agent.
Assuming you've created a secure key with a passphrase, SSH will prompt you for your passphrase for every connection.
Common desktop environments like macOS or GNOME will offer you to cache your passphrase via an SSH agent.
If you are working at the command line, you can alternatively do this directly:
@ -204,9 +223,11 @@ $ ssh-add # enter your passphrase once, then it is cached.
```
Your HTTPS URL used this format: `https://codeberg.org/<user>/<repo>.git`
The SSH URL uses this format: `git@codeberg.org:<user>/<repo>.git` (optionally with `ssh://` at the beginning like this: `ssh://git@codeberg.org:<user>/<repo>.git`).
The SSH URL uses this format: `git@codeberg.org:<user>/<repo>.git` (optionally with `ssh://` at the beginning like
this: `ssh://git@codeberg.org:<user>/<repo>.git`).
Alternatively, you can find the SSH URL by going to your repository page on Codeberg (for example, going to `https://codeberg.org/knut/foobar`), clicking on SSH in the top right corner and copying the URL.
Alternatively, you can find the SSH URL by going to your repository page on Codeberg
(for example, going to `https://codeberg.org/knut/foobar`), clicking on SSH in the top right corner and copying the URL.
4. Verify that your change was successful: