-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.
diff --git a/content/advanced/migrating-repos.md b/content/advanced/migrating-repos.md
index 7238612..3af3611 100644
--- a/content/advanced/migrating-repos.md
+++ b/content/advanced/migrating-repos.md
@@ -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.
-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.
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).
diff --git a/content/advanced/using-webhooks.md b/content/advanced/using-webhooks.md
index 839991a..73cca9e 100644
--- a/content/advanced/using-webhooks.md
+++ b/content/advanced/using-webhooks.md
@@ -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.
@@ -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**.
-
+ 
+ 
+ 
-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.
diff --git a/content/ci/actions.md b/content/ci/actions.md
index e948266..a5c93f1 100644
--- a/content/ci/actions.md
+++ b/content/ci/actions.md
@@ -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 {% 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:
| {% fas_icon "check" %} | ||||
| Configure repository settings in the danger zone (transfer ownership, delete wiki data / repository, archive repository) | ++ Configure repository settings in the danger zone (transfer ownership, delete wiki data / repository, archive repository) + | {% fas_icon "times" %} | {% fas_icon "times" %} | {% fas_icon "times" %} | @@ -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. diff --git a/content/collaborating/resolve-conflicts.md b/content/collaborating/resolve-conflicts.md index a6d6a8c..1927e39 100644 --- a/content/collaborating/resolve-conflicts.md +++ b/content/collaborating/resolve-conflicts.md @@ -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. diff --git a/content/contact.md b/content/contact.md index ac587c7..5ee206f 100644 --- a/content/contact.md +++ b/content/contact.md @@ -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. diff --git a/content/getting-started/email-settings.md b/content/getting-started/email-settings.md index 94a4056..8154229 100644 --- a/content/getting-started/email-settings.md +++ b/content/getting-started/email-settings.md @@ -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. diff --git a/content/getting-started/faq.md b/content/getting-started/faq.md index 578a447..6b3f370 100644 --- a/content/getting-started/faq.md +++ b/content/getting-started/faq.md @@ -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. diff --git a/content/getting-started/first-repository.md b/content/getting-started/first-repository.md index 52aff86..7a5f3ae 100644 --- a/content/getting-started/first-repository.md +++ b/content/getting-started/first-repository.md @@ -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).
-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.
@@ -48,7 +55,9 @@ If you click on the `View [organization]` (here `PolarClub`, you'll be directed
-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:
-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:
-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:
-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.
-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:
@@ -97,9 +120,14 @@ On the `People` tab, you can get an overview of all the people who belong to you
-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.
@@ -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).
diff --git a/content/collaborating/invite-collaborators.md b/content/collaborating/invite-collaborators.md
index aa7dcae..42e7a54 100644
--- a/content/collaborating/invite-collaborators.md
+++ b/content/collaborating/invite-collaborators.md
@@ -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
-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.
diff --git a/content/collaborating/pull-requests-and-git-flow.md b/content/collaborating/pull-requests-and-git-flow.md
index 4532c1a..06f4af5 100644
--- a/content/collaborating/pull-requests-and-git-flow.md
+++ b/content/collaborating/pull-requests-and-git-flow.md
@@ -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
-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:
+
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:
+ 
+
@@ -67,32 +77,43 @@ Here are some important steps:
1. Choose your editor:
+ 
+ 
-> 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`.
>
> 
### 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).
diff --git a/content/getting-started/issue-tracking-basics.md b/content/getting-started/issue-tracking-basics.md
index dfe2757..da827e0 100644
--- a/content/getting-started/issue-tracking-basics.md
+++ b/content/getting-started/issue-tracking-basics.md
@@ -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
diff --git a/content/getting-started/licensing.md b/content/getting-started/licensing.md
index 0f0c6ea..1bb7a0c 100644
--- a/content/getting-started/licensing.md
+++ b/content/getting-started/licensing.md
@@ -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/).
diff --git a/content/getting-started/what-is-codeberg.md b/content/getting-started/what-is-codeberg.md
index c909164..a3c042d 100644
--- a/content/getting-started/what-is-codeberg.md
+++ b/content/getting-started/what-is-codeberg.md
@@ -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.
---
diff --git a/content/getting-started/wiki.md b/content/getting-started/wiki.md
index 556e71e..80276d3 100644
--- a/content/getting-started/wiki.md
+++ b/content/getting-started/wiki.md
@@ -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 `
### 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.
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).
@@ -44,9 +48,14 @@ The commit section is at the bottom of the edit window:
-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).
diff --git a/content/git/configuring-git.md b/content/git/configuring-git.md
index da8c71e..083048a 100644
--- a/content/git/configuring-git.md
+++ b/content/git/configuring-git.md
@@ -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.
diff --git a/content/git/index.md b/content/git/index.md
index 72b855f..90883c8 100644
--- a/content/git/index.md
+++ b/content/git/index.md
@@ -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 %}
diff --git a/content/git/squash-commits.md b/content/git/squash-commits.md
index 3c2c6e6..b57a883 100644
--- a/content/git/squash-commits.md
+++ b/content/git/squash-commits.md
@@ -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.
diff --git a/content/git/using-lfs.md b/content/git/using-lfs.md
index f9937a7..f13881b 100644
--- a/content/git/using-lfs.md
+++ b/content/git/using-lfs.md
@@ -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
diff --git a/content/git/using-tags.md b/content/git/using-tags.md
index 2b1b33d..73fe479 100644
--- a/content/git/using-tags.md
+++ b/content/git/using-tags.md
@@ -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 
+
-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:
@@ -76,5 +89,8 @@ Here, you can edit the release if needed, and you can also download the source c
-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).
diff --git a/content/home.md b/content/home.md
index 1a0fd16..8bf8d82 100644
--- a/content/home.md
+++ b/content/home.md
@@ -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.
diff --git a/content/improving-codeberg/contributing-code.md b/content/improving-codeberg/contributing-code.md
index edaa2f3..1164e8e 100644
--- a/content/improving-codeberg/contributing-code.md
+++ b/content/improving-codeberg/contributing-code.md
@@ -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).
diff --git a/content/improving-codeberg/donate.md b/content/improving-codeberg/donate.md
index bba4700..6298ba4 100644
--- a/content/improving-codeberg/donate.md
+++ b/content/improving-codeberg/donate.md
@@ -36,9 +36,12 @@ develop new features and sustain the Free Software ecosystem around.
BIC: GENODEF1SLR
- 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.
+
+
+
## 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:
+
+
+
+
+
+
+ 
+ 
+ 
+ 
+
and `:forgejo:` which is rendered as 
.
+Some examples are `:codeberg:` which is rendered as
+
-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.
+ 
+