From 941914f6986b93a2aef7592b2f857317bad38dee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Javier=20P=C3=A9rez?= Date: Fri, 21 Nov 2025 12:35:05 +0100 Subject: [PATCH] Fix lint issues (#629) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit # Changelog The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Fixed - Lint issues: - Line length ([MD013](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md013.md)). - Heading levels should only increment by one level at a time ([MD001](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md001.md)). - Link fragments should be valid ([MD051](https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md051.md)). --- Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/629 Reviewed-by: Gusted Co-authored-by: Javier Pérez Co-committed-by: Javier Pérez --- .markdownlint.yaml | 6 ++ .prettierignore | 1 + content/ci/agents.md | 55 ++++++++++++++----- content/ci/index.md | 9 ++- content/codeberg-pages/index.md | 3 +- content/codeberg-pages/pushing-output.md | 12 ++-- content/codeberg-pages/using-custom-domain.md | 28 +++++++--- content/collaborating/create-organization.md | 3 +- content/getting-started/faq.md | 45 +++++++++++---- .../getting-started/issue-tracking-basics.md | 14 ++--- content/git/reduce-size.md | 52 ++++++++++++------ .../docs-contributor-faq.md | 6 +- content/improving-documentation/index.md | 2 +- content/markdown/topics.md | 2 +- content/markdown/using-links.md | 6 +- content/security/2fa.md | 7 ++- content/security/ssh-key.md | 7 ++- 17 files changed, 176 insertions(+), 82 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 1280108..c0df7a9 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -135,3 +135,9 @@ MD046: MD048: # Code fence style style: 'backtick' + +# MD051/link-fragments - Link fragments should be valid +MD051: + # Ignore link fragments ending with simple URL percent-encoding. + # For example, to allow targeting headings ending with a question mark ('?'). + ignored_pattern: "%\\w{2}$" diff --git a/.prettierignore b/.prettierignore index bd5535a..46430d7 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1 +1,2 @@ pnpm-lock.yaml +.pnpm-store/ diff --git a/content/ci/agents.md b/content/ci/agents.md index db614ca..1256872 100644 --- a/content/ci/agents.md +++ b/content/ci/agents.md @@ -5,21 +5,29 @@ eleventyNavigation: parent: CI --- -Codeberg's CI resources are run by volunteers, and as such have some limitations in terms of shared resources. However, it is not necessary to self-host and administer your own full CI instance as you can add your own Woodpecker agents to your user or organization. +Codeberg's CI resources are run by volunteers, and as such have some limitations in terms of shared resources. +However, it is not necessary to self-host and administer your own full CI instance as you can add your own Woodpecker +agents to your user or organization. -Some example use-cases where a self-hosted agent is recommended include: when you want faster feedback from CI, to handle long-running or resource-intensive jobs, creating specialized environments for specific architectures, hardware-in-the-loop testing, or setting up larger networked integration tests. +Some example use-cases where a self-hosted agent is recommended include: when you want faster feedback from CI, to +handle long-running or resource-intensive jobs, creating specialized environments for specific architectures, +hardware-in-the-loop testing, or setting up larger networked integration tests. -This guide will walk you through [setting up your own Woodpecker agent](https://woodpecker-ci.org/docs/administration/configuration/agent) to communicate with Codeberg's CI infrastructure and configuring your workflows to use it. +This guide will walk you through [setting up your own Woodpecker agent](https://woodpecker-ci.org/docs/administration/configuration/agent) +to communicate with Codeberg's CI infrastructure and configuring your workflows to use it. ## Obtaining an agent token {% admonition "info" "An agent may only be added to one user or org" %} -Any agent can only be assigned to either a single user or a single organization. This means that you will need to create multiple agents if you want to share resources with other users or organizations. +Any agent can only be assigned to either a single user or a single organization. +This means that you will need to create multiple agents if you want to share resources with other users or organizations. {% endadmonition %} -Before deploying the agent, you need to obtain an agent token from Codeberg's Woodpecker instance. The agent token is a secret shared between Codeberg's CI instance and your agent in order to facilitate the execution of workflows. +Before deploying the agent, you need to obtain an agent token from Codeberg's Woodpecker instance. +The agent token is a secret shared between Codeberg's CI instance and your agent in order to facilitate the execution +of workflows. To do so, please follow the instructions immediately below for users, and follow the instructions below that for organizations. @@ -45,9 +53,11 @@ This token will be used to set up the Woodpecker Agent in the next step. ## Creating a Woodpecker Agent -The Woodpecker Agent is released as a docker image and as Linux distribution packages. The installation is simplified for Docker Compose and Helm deployments. +The Woodpecker Agent is released as a docker image and as Linux distribution packages. +The installation is simplified for Docker Compose and Helm deployments. -The following configurations are modified to work with Codeberg's CI service from the official documentation. For more information on the specific variables available to configure, [please read the Woodpecker agent documentation](https://woodpecker-ci.org/docs/administration/configuration/agent). +The following configurations are modified to work with Codeberg's CI service from the official documentation. +For more information on the specific variables available to configure, [please read the Woodpecker agent documentation](https://woodpecker-ci.org/docs/administration/configuration/agent). ### Creating an agent with Docker Compose @@ -77,11 +87,14 @@ volumes: #### Automatically scaling your agents on demand -Woodpecker also has a container to automatically scale agents. This is not required for Kubernetes clusters. [Please read the autoscaler documentation for more information](https://woodpecker-ci.org/docs/administration/configuration/autoscaler) +Woodpecker also has a container to automatically scale agents. This is not required for Kubernetes clusters. +[Please read the autoscaler documentation for more information](https://woodpecker-ci.org/docs/administration/configuration/autoscaler) ### Managing agents with Kubernetes and Helm -Alternatively, Kubernetes can aid in managing your agents. It provides automatic scaling, metrics, topology management and whole host of other features that can be tuned for a particular project. For more details, [please see the Helm chart for Woodpecker Agents](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/charts/agent/README.md). +Alternatively, Kubernetes can aid in managing your agents. It provides automatic scaling, metrics, topology management +and whole host of other features that can be tuned for a particular project. +For more details, [please see the Helm chart for Woodpecker Agents](https://github.com/woodpecker-ci/helm/blob/main/charts/woodpecker/charts/agent/README.md). Only the agent chart is required. @@ -91,9 +104,14 @@ helm install woodpecker/agent oci://ghcr.io/woodpecker-ci/helm/woodpecker --vers ## Configuring workflows to use your agent -Now that you have added your agent to Codeberg CI, you can configure your workflows to use your new agent. This is recommended for resource intensive and long running jobs. This can also be used to create specialized agents that have access to hardware or other environmental configurations. +Now that you have added your agent to Codeberg CI, you can configure your workflows to use your new agent. +This is recommended for resource intensive and long running jobs. This can also be used to create specialized agents +that have access to hardware or other environmental configurations. -For example, if you have a workflow you want to run on ARM and RISCV architecture, these require adding your own agent (as of the time of writing). You can use the following workflow as an example. For the specifics of the syntax, [please read the the Woodpecker Docs](https://woodpecker-ci.org/docs/usage/workflow-syntax#filter-by-platform). The platforms are [written as Go platforms](https://go.dev/doc/install/source): +For example, if you have a workflow you want to run on ARM and RISCV architecture, these require adding your own agent +(as of the time of writing). You can use the following workflow as an example. For the specifics of the syntax, +[please read the the Woodpecker Docs](https://woodpecker-ci.org/docs/usage/workflow-syntax#filter-by-platform). +The platforms are [written as Go platforms](https://go.dev/doc/install/source): ```yaml matrix: @@ -141,11 +159,16 @@ steps: platform: */riscv64 ``` -You can also add labels to the agent's configuration that can be used in workflows. Labels are key-value maps assigned to specific agents by using the `WOODPECKER_AGENT_LABELS` variable. +You can also add labels to the agent's configuration that can be used in workflows. +Labels are key-value maps assigned to specific agents by using the `WOODPECKER_AGENT_LABELS` variable. -For example, say you're creating an IoT project that needs a machine with a specific peripheral, such as a LoRa radio, for testing. You have an agent that has the module attached and you need a way to tell Woodpecker to use that particular machine. [Radio hardware often depends on what part of the world you're in,](https://en.wikipedia.org/wiki/ITU_Region) you also want to specify where your agent is located. +For example, say you're creating an IoT project that needs a machine with a specific peripheral, such as a LoRa radio, +for testing. You have an agent that has the module attached and you need a way to tell Woodpecker to +use that particular machine. [Radio hardware often depends on what part of the world you're in,](https://en.wikipedia.org/wiki/ITU_Region) +you also want to specify where your agent is located. -Here is how to add the necessary environment variable to [an agent's docker compose script](#creating-an-agent-with-docker-compose) to label it in ITU Region 1 (Europe is in Region 1) with a lora module attached: +Here is how to add the necessary environment variable to [an agent's docker compose script](#creating-an-agent-with-docker-compose) +to label it in ITU Region 1 (Europe is in Region 1) with a lora module attached: ```yaml # Agent configuration goes here... @@ -172,7 +195,9 @@ steps: - make test ``` -If you had a teammate running an agent in another continent, you would then change the location label in both the workflow and the agent from region-1 to region-2 or region-3 accordingly. If you wanted to run tests with a different peripheral, you'd change the peripheral label, etc. +If you had a teammate running an agent in another continent, you would then change the location label in both the +workflow and the agent from region-1 to region-2 or region-3 accordingly. If you wanted to run tests with a different +peripheral, you'd change the peripheral label, etc. ## References diff --git a/content/ci/index.md b/content/ci/index.md index 723e849..ce38b40 100644 --- a/content/ci/index.md +++ b/content/ci/index.md @@ -54,7 +54,8 @@ If you wish to see examples of integrating Woodpecker-CI with codeberg, please c ### Adding Self-Hosted Agents -Woodpecker enables users and organizations to add their own agents for running workflows. This is recommended for resource-intensive tasks, or if you want to run jobs on specific architectures. +Woodpecker enables users and organizations to add their own agents for running workflows. +This is recommended for resource-intensive tasks, or if you want to run jobs on specific architectures. More information can be found on the [Adding Self-Hosted Agents page](./agents). @@ -69,8 +70,10 @@ for more information. ## Using Forgejo Actions Forgejo, the software Codeberg is built on, offers a CI/CD feature called Actions. -Forgejo Actions can be used with self-hosted runners and Codeberg also provides a hosted version in a limited fashion in open alpha. +Forgejo Actions can be used with self-hosted runners and Codeberg also provides a hosted version in +a limited fashion in open alpha. Further information such as how to run Forgejo Actions is available in [Using Forgejo Actions (Self-hosted) page](./actions). -If you want to learn more about the differences between the Woodpecker CI and Forgejo Actions, you can [find those on the actions meta repository](https://codeberg.org/actions/meta). +If you want to learn more about the differences between the Woodpecker CI and Forgejo Actions, +you can [find those on the actions meta repository](https://codeberg.org/actions/meta). diff --git a/content/codeberg-pages/index.md b/content/codeberg-pages/index.md index 94cc5d7..979d797 100644 --- a/content/codeberg-pages/index.md +++ b/content/codeberg-pages/index.md @@ -75,7 +75,8 @@ can be accessed via `https://username.codeberg.page/@docs~develop/README.md`). You can replace the default 404 error page that Codeberg Pages will show for missing pages with your own version if you prefer. To do so start by writing your own HTML file that you want to serve instead. -After creating the HTML with your custom error message, save it as `404.html` in the root of your repository that you use to serve your Codeberg Page. +After creating the HTML with your custom error message, save it as `404.html` in the root of your +repository that you use to serve your Codeberg Page. From then on, your `404.html` file will be served when the error is encountered. diff --git a/content/codeberg-pages/pushing-output.md b/content/codeberg-pages/pushing-output.md index 4604902..d4de88d 100644 --- a/content/codeberg-pages/pushing-output.md +++ b/content/codeberg-pages/pushing-output.md @@ -94,10 +94,14 @@ You can find more information in the [Codeberg Pages](/codeberg-pages/) section. ## Using a CI -Both the [Woodpecker CI](/ci/#using-codeberg's-instance-of-woodpecker-ci) and the [hosted Forgejo Actions](/ci/actions/) can be used to automate the build and deployment of your static website. +Both the [Woodpecker CI](/ci/#using-codeberg's-instance-of-woodpecker-ci) and the [hosted Forgejo Actions](/ci/actions/) +can be used to automate the build and deployment of your static website. -For the Woodpecker CI, you can see the [existing example workflows in the `Codeberg-CI/examples` repo](https://codeberg.org/Codeberg-CI/examples), which provides examples for Jekyll, Hugo, Zola and many other popular SSG. +For the Woodpecker CI, you can see the [existing example workflows in the `Codeberg-CI/examples` repo](https://codeberg.org/Codeberg-CI/examples), +which provides examples for Jekyll, Hugo, Zola and many other popular SSG. -Currently, we do not have any examples for the Forgejo Actions yet, but individual SSG tools might have details in their own documentation. +Currently, we do not have any examples for the Forgejo Actions yet, but individual SSG tools might +have details in their own documentation. -Note that if you use Forgejo Actions to publish the website, you should make sure that `.domains` file will be preserved in the root directory of the **output** branch or repository. +Note that if you use Forgejo Actions to publish the website, you should make sure that `.domains` +file will be preserved in the root directory of the **output** branch or repository. diff --git a/content/codeberg-pages/using-custom-domain.md b/content/codeberg-pages/using-custom-domain.md index cf36e75..b4080f1 100644 --- a/content/codeberg-pages/using-custom-domain.md +++ b/content/codeberg-pages/using-custom-domain.md @@ -19,7 +19,9 @@ The value of the CAA record would look like `letsencrypt.org;accounturi=https:// For custom domains, two things are required: -- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages. The file should contain a list of all external domains that shall be usable to access that repository, according to the following rules: +- a `.domains` file in the repository and branch where your files reside which you want to publish via Codeberg Pages. + The file should contain a list of all external domains that shall be usable to access that repository, + according to the following rules: - One domain per line, you can leave lines empty and comment out lines with `#`. - The first domain is the main domain, all other domains in the file will be redirected to the first one. @@ -81,15 +83,18 @@ Depending on from where you want to serve your files, there is a naming scheme f {% admonition "warning" "Repository names with dots are not supported" %} -Repository names containing dots (`.`) are **not supported** for custom domains. The Pages server uses dots as delimiters to parse the repository name, branch, and owner from DNS records. +Repository names containing dots (`.`) are **not supported** for custom domains. +The Pages server uses dots as delimiters to parse the repository name, branch, and owner from DNS records. -For example, if your repository is named `my.project`, the TXT record `my.project.username.codeberg.page` will be incorrectly parsed as: +For example, if your repository is named `my.project`, the TXT record `my.project.username.codeberg.page` +will be incorrectly parsed as: - Branch: `my` - Repository: `project` - Owner: `username` -**Solution:** If you need to use a custom domain, rename your repository to use hyphens (`-`) or underscores (`_`) instead of dots. For example, rename `my.project` to `my-project`. +**Solution:** If you need to use a custom domain, rename your repository to use hyphens (`-`) or +underscores (`_`) instead of dots. For example, rename `my.project` to `my-project`. {% endadmonition %} @@ -238,7 +243,8 @@ myself.example.com For the DNS configuration: -- if the domain is not the apex of the zone and does not have other services such as email, you should always use a CNAME record: +- if the domain is not the apex of the zone and does not have other services such as email, + you should always use a CNAME record: - name `myself.example.com`, type `CNAME`, data `frida.codeberg.page` - otherwise, if ALIAS can be used, two DNS records will be needed: @@ -252,7 +258,8 @@ For the DNS configuration: ### Personal/Organization site, apex domain -In this case, we want our _Personal_/_Organization_ pages available at the URL `https://example.com`. We also want the URL `https://www.example.com` to redirect to the apex domain. +In this case, we want our _Personal_/_Organization_ pages available at the URL `https://example.com`. +We also want the URL `https://www.example.com` to redirect to the apex domain. The `.domains` file contains the following: @@ -261,7 +268,8 @@ example.com www.example.com ``` -_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL and redirect the apex domain instead._ +_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL_ +_and redirect the apex domain instead._ For the DNS configuration, CNAME records CANNOT be used for the apex domain, so: @@ -290,7 +298,8 @@ colormix-app.example.com For the DNS configuration: -- if the domain is not the apex of the zone and does not have other services such as email, you should always use a CNAME record: +- if the domain is not the apex of the zone and does not have other services such as email, + you should always use a CNAME record: - name `colormix-app.example.com`, type `CNAME`, data `colormix.frida.codeberg.page` - otherwise, if ALIAS can be used, two DNS records will be needed: @@ -320,7 +329,8 @@ example.com www.example.com ``` -_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL and redirect the apex domain instead._ +_You may also put the `www` subdomain on the first line if you wish to use it as the canonical URL_ +_and redirect the apex domain instead._ For the DNS configuration, CNAME records CANNOT be used for the apex domain, so: diff --git a/content/collaborating/create-organization.md b/content/collaborating/create-organization.md index 5c9849b..b55463e 100644 --- a/content/collaborating/create-organization.md +++ b/content/collaborating/create-organization.md @@ -114,7 +114,8 @@ To do this, go to the `Teams` tab and click on the team you want to edit: Click on `Settings` to edit the team as shown above for the creation of a team. This is also where you can add or remove members to/from a team, and assign repositories to them. It is also possible to invite people by email. -This also works for email addresses not associated with any Codeberg account, in which case they will be prompted to create an account first. +This also works for email addresses not associated with any Codeberg account, in which case they +will be prompted to create an account first. ## People diff --git a/content/getting-started/faq.md b/content/getting-started/faq.md index fe1f0b8..368360c 100644 --- a/content/getting-started/faq.md +++ b/content/getting-started/faq.md @@ -112,19 +112,32 @@ but we acknowledge that private repositories are useful or necessary at times. The rules of thumb are: -- If you are a **contributor to free/libre software projects**, we allow up to **100 MB of private content** for your convenience. Use it for your personal notes, your side project or any other you want to keep private. +- If you are a **contributor to free/libre software projects**, we allow up to **100 MB of private content** + for your convenience. Use it for your personal notes, your side project or any other you want to keep private.
I need more clarification on this rule! We know that this rule is not the most precise, and it is mostly evaluated on a case-by-case basis. - - Our goal is to avoid abuse of our infrastructure for purposes not in line with our mission. If you are a heavy contributor to the free/libre software ecosystem and this is apparent from your profile, we might also accept if you use slightly more than 100 MB. - - If you are not heavily contributing to free/libre software, but obviously supporting the spirit of the ecosystem (e.g. by participating in projects by creating issues, doing translations or submitting tiny fixes), we're also happy to have you aboard. - - If you do not contribute to free/libre software (or if it is limited to your personal homepage), and we feel like you only abuse Codeberg for storing your commercial projects or media backups, we might get unhappy about that. + + Our goal is to avoid abuse of our infrastructure for purposes not in line with our mission. + If you are a heavy contributor to the free/libre software ecosystem and this is apparent from your profile, + we might also accept if you use slightly more than 100 MB. + + If you are not heavily contributing to free/libre software, but obviously supporting the spirit of the ecosystem + (e.g. by participating in projects by creating issues, doing translations or submitting tiny fixes), + we're also happy to have you aboard. + + If you do not contribute to free/libre software (or if it is limited to your personal homepage), + and we feel like you only abuse Codeberg for storing your commercial projects or media backups, + we might get unhappy about that.
-- If your private content is strictly required for a free/libre software project (like team-internal discussions, preparation of security patches, or preparing a release for a limited amount of time), private content will also be tolerated. -- If you use more than 100 MB of private storage for the use cases mentioned earlier, please [send us a request](https://codeberg.org/Codeberg-e.V./requests) and we can evaluate it. -- If you do not contribute to any free/libre software project at all, Codeberg is unfortunately not the right place for you. However, [check out the alternatives](/getting-started/what-is-codeberg/#alternatives-to-codeberg), we're sure you'll find a cozy place for your work. + +- If your private content is strictly required for a free/libre software project (like team-internal discussions, + preparation of security patches, or preparing a release for a limited amount of time), + private content will also be tolerated. +- If you use more than 100 MB of private storage for the use cases mentioned earlier, please [send us a request](https://codeberg.org/Codeberg-e.V./requests) + and we can evaluate it. +- If you do not contribute to any free/libre software project at all, Codeberg is unfortunately not + the right place for you. However, [check out the alternatives](/getting-started/what-is-codeberg/#alternatives-to-codeberg), + we're sure you'll find a cozy place for your work. ### What is the size limit for my repositories? Are there quotas for packages, LFS, ...? @@ -168,8 +181,16 @@ For your convenience, we allow [small amounts of works](#how-about-private-repos However, we do not accept any payments for exceptions to our rules: -- **Proprietary or private content**: The goal of our non-profit association is to support free/libre software development, not to become a "general-purpose code forge" like commercial code forges are. Adding such payment-based support for proprietary features would not only potentially challenge our non-profit status, but also hurt our community aspect. It would also require substantial time and energy to support such efforts, that we would rather spend on support free/libre projects. -- **Storage and CI/CD resources**: We happily accept free/libre projects of any size, within the realm of what our infrastructure can provide, independent of donations or payments. However, given that our infrastructure and the environment are common goods, please do not be wasteful with these resources and try to optimize your use of them. If your project hits to our resource limits despite best efforts of optimizing, please [reach out to discuss the options](https://codeberg.org/Codeberg-e.V./requests). +- **Proprietary or private content**: The goal of our non-profit association is to support free/libre software + development, not to become a "general-purpose code forge" like commercial code forges are. + Adding such payment-based support for proprietary features would not only potentially challenge our non-profit status, + but also hurt our community aspect. It would also require substantial time and energy to support such efforts, + that we would rather spend on support free/libre projects. +- **Storage and CI/CD resources**: We happily accept free/libre projects of any size, within the realm of what our + infrastructure can provide, independent of donations or payments. However, given that our infrastructure and the + environment are common goods, please do not be wasteful with these resources and try to optimize your use of them. + If your project hits to our resource limits despite best efforts of optimizing, + please [reach out to discuss the options](https://codeberg.org/Codeberg-e.V./requests). ## Why can't I mirror repositories from other code-hosting websites? diff --git a/content/getting-started/issue-tracking-basics.md b/content/getting-started/issue-tracking-basics.md index da827e0..a2489f1 100644 --- a/content/getting-started/issue-tracking-basics.md +++ b/content/getting-started/issue-tracking-basics.md @@ -11,7 +11,7 @@ Besides their original purpose - reporting bugs to a project's maintainer - they can be used to suggest enhancements, ask for new features, discuss a project's direction, ask questions and much more. -### The Issue Tracker +## The Issue Tracker Issues List @@ -35,7 +35,7 @@ An issue can have an assignee, meaning someone responsible for resolving or mode the issue. Their profile picture, with a link to their profile, can be seen in the issue list. -### Life of an Issue +## Life of an Issue Once an issue in the Issue Tracker has been created, it will usually pass through a process of review, discussion and closure, which can be more or less strictly defined, @@ -64,9 +64,9 @@ consider forking it, if you want to assume responsibility for it (or, rather, yo {% endadmonition %} -### Things to consider +## Things to consider -#### Security bugs +### Security bugs If the bug you have found has security implications, **do not create an issue right away!** Instead try contacting the project's maintainers privately. @@ -82,7 +82,7 @@ project at severe risk**. {% endadmonition %} -#### Existing issues +### Existing issues Before creating a new issue, please make sure that there isn't already an existing issue about, i.e., the bug you want to report or the feature you want to request. @@ -93,7 +93,7 @@ if there is something more that you can contribute to it. You should also make sure that the issue has not already been solved by having a look at the closed issues **(3)** as well. -#### Try to be precise and helpful +### Try to be precise and helpful Project maintainers love precise information about why, i.e., a bug is happening. @@ -104,7 +104,7 @@ If you can provide that information, it will be easier for the project maintaine to quickly resolve your issue. And if you want it resolved even quicker, consider writing a Pull Request solving the issue (if possible). -#### Be (reasonably) patient +### Be (reasonably) patient Please remember that many project maintainers work on their free software projects in their free time. Some maintainers may answer you within minutes, others within days. diff --git a/content/git/reduce-size.md b/content/git/reduce-size.md index b899f1e..49bd77c 100644 --- a/content/git/reduce-size.md +++ b/content/git/reduce-size.md @@ -5,29 +5,35 @@ eleventyNavigation: parent: Git --- -The best way to keep your repository at a manageable size is [to use the `.gitignore` feature](/git/git-ignore/) to make sure large files are not being part of your git repository in the first place. +The best way to keep your repository at a manageable size is [to use the `.gitignore` feature](/git/git-ignore/) to make +sure large files are not being part of your git repository in the first place. But sometimes it can be too late, as you already committed large files in the past. Or maybe at some point you legitimately needed some larger files, but now they are obsolete. {% admonition "Tip" %} -The removal of files from the Git history is also useful if you accidentally pushed secrets such as passwords, API keys or other private information to your repository. +The removal of files from the Git history is also useful if you accidentally pushed secrets such as passwords, +API keys or other private information to your repository. Without rewriting the history, this information would permanently linger in your Git history. {% endadmonition %} -Either way, you might want to permanently remove files from your Git repository, to shrink its overall size or to remove individual files that weren't meant to be committed to it. +Either way, you might want to permanently remove files from your Git repository, to shrink its overall size or to remove +individual files that weren't meant to be committed to it. -The first step to achieving this, is deleting the files from the current state of your branch, using the regular `git rm filename.txt` approach. +The first step to achieving this, is deleting the files from the current state of your branch, +using the regular `git rm filename.txt` approach. Once these files are no longer in the current `HEAD` of your branch, you can rewrite the history of your Git repository. -This ensures that the files do not remain in the overall Git history, where they would continue to take up space, or in case of accidentally committed secrets, remain accessible to others. +This ensures that the files do not remain in the overall Git history, where they would continue to take up space, +or in case of accidentally committed secrets, remain accessible to others. {% admonition "warning" %} **Rewriting your Git history is a destructive process.** You should make a backup of your repository before attempting rewriting the history. -Additionally, once you have rewritten the history, everyone who has made a working copy of your repository will have ensure that they have copies with the correct, new history. +Additionally, once you have rewritten the history, everyone who has made a working copy of your +repository will have ensure that they have copies with the correct, new history. If your repository has open pull requests, this will introduce conflicts for these, too. @@ -37,8 +43,10 @@ If your repository has open pull requests, this will introduce conflicts for the ### Installing the necessary tools -Install [git-filter-repo](https://github.com/newren/git-filter-repo), which will be used to actually perform the history rewrites. -Optionally, you can also install [git-sizer](https://github.com/github/git-sizer/tree/master), if you want to find large files that are no longer used in your history. +Install [git-filter-repo](https://github.com/newren/git-filter-repo), which will be used to actually +perform the history rewrites. +Optionally, you can also install [git-sizer](https://github.com/github/git-sizer/tree/master), +if you want to find large files that are no longer used in your history. ### Make a mirror clone of the repository @@ -54,10 +62,12 @@ It's important that you clone your repository using the `--mirror` flag to be ab ## Identifying files to remove & removing them -### Optionally: Run git-filter-repo’s analyze command. +### Optionally: Run git-filter-repo’s analyze command -This optional step can help you identify files that are already deleted from the current state of your branch, but that are still in the history. -For example, this would help for finding be large build files or assets that were accidentally committed and already, but still take space in the history. +This optional step can help you identify files that are already deleted from the current state of your branch, +but that are still in the history. +For example, this would help for finding be large build files or assets that were accidentally committed and already, +but still take space in the history. To identify such files, you can run: @@ -73,7 +83,8 @@ git-sizer -v ### Run git-filter-repo to rewrite the history and permanently remove the files This is the actual history-rewriting that will take place on your local mirror clone. -As a reminder: You should only try to use `git-filter-repo` to remove files from your repository's history that are already no longer in use in your current `HEAD`. +As a reminder: You should only try to use `git-filter-repo` to remove files from your repository's history that are +already no longer in use in your current `HEAD`. For example, let's assume you at some point accidentally had committed a folder `dist/`. You already removed it from the current state of your repository using `git rm -r dist/`. @@ -85,9 +96,10 @@ To achieve this, you can run: git-filter-repo --path dist/ --invert-paths ``` -You give `dist/` as the path, and using `--invert-paths` you tell `git-filter-repo` that you want to keep all files, except the ones specified using `--path`. +You give `dist/` as the path, and using `--invert-paths` you tell `git-filter-repo` that you want to keep all files, +except the ones specified using `--path`. -5. Run git-filter-repo analyze/git-sizer again to check that the repository size has indeed been reduced: +1. Run git-filter-repo analyze/git-sizer again to check that the repository size has indeed been reduced: ```shell git-filter-repo --analyze --force @@ -98,7 +110,9 @@ You give `dist/` as the path, and using `--invert-paths` you tell `git-filter-re git-sizer -v ``` -So far, all of these changes have been applied to your local mirror copy of your repository, once you are happy with the rewritten history (e.g. that the size has successfully been reduced or that the secrets were removed), you can push those changes to Codeberg. +So far, all of these changes have been applied to your local mirror copy of your repository, +once you are happy with the rewritten history (e.g. that the size has successfully been reduced or +that the secrets were removed), you can push those changes to Codeberg. ## Replacing the history on Codeberg @@ -106,11 +120,12 @@ So far, all of these changes have been applied to your local mirror copy of your **The following step replaces your repository's history on Codeberg in a destructive operation.** -Ensure that you have a pre-rewrite backup of your repository somewhere, otherwise you will not be able to undo in case anything goes wrong. +Ensure that you have a pre-rewrite backup of your repository somewhere, otherwise you will not be able +to undo in case anything goes wrong. {% endadmonition %} -6. Turn off the mirror flag and carry out force pushes to your remote +1. Turn off the mirror flag and carry out force pushes to your remote ```shell git config --unset remote.origin.mirror @@ -129,7 +144,8 @@ For users who have on-going local work, the following steps should work, unless 1. `git fetch` the remote (not `pull`, to avoid errors/warnings) 2. `git checkout` the local branch that has current work -3. `git rebase origin/branch` with `origin` being the remote for the repository and `branch` being the branch you are working against. +3. `git rebase origin/branch` with `origin` being the remote for the repository and `branch` being + the branch you are working against. This will rebase the local work onto the remote's main branch (or the branch you are working against at). diff --git a/content/improving-documentation/docs-contributor-faq.md b/content/improving-documentation/docs-contributor-faq.md index 3cffabe..593d4e3 100644 --- a/content/improving-documentation/docs-contributor-faq.md +++ b/content/improving-documentation/docs-contributor-faq.md @@ -9,11 +9,11 @@ eleventyNavigation: The intent of this document is to give answers to a number of questions that might arise when starting to contribute to Codeberg Documentation. If your question is not listed, feel free to [ask in the issue tracker](https://codeberg.org/Codeberg/Documentation/issues). -### How should files be named? +## How should files be named? Please adhere to [kebab-Case](https://en.wikipedia.org/wiki/Kebab_case) naming rules for any files in Codeberg Documentation. -### When is my contribution being approved? +## When is my contribution being approved? A Pull Request to Codeberg/Documentation will be reviewed by at least one other Codeberg Documentation collaborators and if your Pull Request is approved, they will merge it into the main branch. @@ -27,7 +27,7 @@ There are a number of exceptions to the rule above: - For changes that are critical, e.g. ones that might legally affect Codeberg e.V., the chairperson of Codeberg e.V. will need to approve of the changes as well. -### How to link to non-existing articles? / Draft Articles +## How to link to non-existing articles? / Draft Articles While it is not directly possible to link to non-existing articles, it is possible to create Draft Articles, which are articles that cannot be localized for example via the menu, but which do exist under their URL and do show a diff --git a/content/improving-documentation/index.md b/content/improving-documentation/index.md index 4517cbb..546a5e1 100644 --- a/content/improving-documentation/index.md +++ b/content/improving-documentation/index.md @@ -29,7 +29,7 @@ We're very happy you're considering to contribute to Codeberg Documentation! {% endif %} {%- endfor %} -### How do I contribute to Codeberg Documentation? +## How do I contribute to Codeberg Documentation? To contribute to Codeberg Documentation, the first thing you should do (if you haven't already done it) is to create your own fork of the [Codeberg/Documentation repository](https://codeberg.org/Codeberg/Documentation). diff --git a/content/markdown/topics.md b/content/markdown/topics.md index 24c97d0..72b66f9 100644 --- a/content/markdown/topics.md +++ b/content/markdown/topics.md @@ -23,7 +23,7 @@ for further details. **Note:** This document may seem a little unstructured, as there are a bunch of topics with only a small amount of text. Unfortunately, there is no other way to present Topics in Markdown. -### Examples of topics with hash characters +## Examples of topics with hash characters ```shell # 1st Topic diff --git a/content/markdown/using-links.md b/content/markdown/using-links.md index 34cc363..274eb47 100644 --- a/content/markdown/using-links.md +++ b/content/markdown/using-links.md @@ -75,7 +75,8 @@ This is rendered as: ## Alternative link syntax -The link parser used in Forgejo can also work with the _double square brackets_ syntax in issues and other places where markdown is rendered: +The link parser used in Forgejo can also work with the _double square brackets_ syntax in issues and +other places where markdown is rendered: ```markdown [[https://codeberg.org/]] @@ -101,7 +102,8 @@ will be rendered as [This is a link to the markdown section of the docs](/markdo {% admonition "warning" %} -Be aware that this syntax is 'inverted' compared to the one that [MediaWiki](https://www.mediawiki.org) uses (i.e. `[[https://example.com|link title]]`). +Be aware that this syntax is 'inverted' compared to the one that [MediaWiki](https://www.mediawiki.org) +uses (i.e. `[[https://example.com|link title]]`). For compatibility reasons, Forgejo can also convert those links, but only if full paths are specified. This means `[[https://example.com|link title]]` will also be converted to "[link title](https://example.com)". diff --git a/content/security/2fa.md b/content/security/2fa.md index cc81746..c26c747 100644 --- a/content/security/2fa.md +++ b/content/security/2fa.md @@ -26,8 +26,11 @@ You will need an authenticator app installed on your phone. If you don't already have an authenticator app and you're not sure which app to use, have a look at Aegis Authenticator ([F-Droid](https://f-droid.org/de/packages/com.beemdevelopment.aegis/) | -[Google Play Store](https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis&hl=en_US)), Authenticator ([App Store](https://itunes.apple.com/app/authenticator/id766157276)) or Ente Auth ([F-Droid](https://f-droid.org/packages/io.ente.auth/) | -[Google Play Store](https://play.google.com/store/apps/details?id=io.ente.auth) | [App Store](https://apps.apple.com/app/ente-auth-2fa-authenticator/id6444121398)). +[Google Play Store](https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis&hl=en_US)), +Authenticator ([App Store](https://itunes.apple.com/app/authenticator/id766157276)) +or Ente Auth ([F-Droid](https://f-droid.org/packages/io.ente.auth/) | +[Google Play Store](https://play.google.com/store/apps/details?id=io.ente.auth) | +[App Store](https://apps.apple.com/app/ente-auth-2fa-authenticator/id6444121398)). #### Step 1: Navigate to your user settings diff --git a/content/security/ssh-key.md b/content/security/ssh-key.md index b69425e..04b54ae 100644 --- a/content/security/ssh-key.md +++ b/content/security/ssh-key.md @@ -73,10 +73,11 @@ be prompted to touch it to continue. ## Add the SSH key to Codeberg -1. Copy the SSH key to your clipboard. You must only copy the public key not the private one. You can identify it by the - `.pub` suffix. By default, you can find the public key in `$HOME/.ssh/id_ed25519.pub`. +1. Copy the SSH key to your clipboard. You must only copy the public key not the private one. + You can identify it by the `.pub` suffix. By default, you can find the public key in `$HOME/.ssh/id_ed25519.pub`. - On Linux, assuming you are using Wayland, you can use `wl-copy` on the command line. You may need to install `wl-clipboard` from your package manager. + On Linux, assuming you are using Wayland, you can use `wl-copy` on the command line. + You may need to install `wl-clipboard` from your package manager. ```shell wl-copy -t text/plain < ~/.ssh/id_ed25519.pub