8.8 KiB

key title parent
ContributingCode Contributing Code 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. Some things are always changing, and we're not (yet) good at continuously updating the docs on that — but we're always glad to help you with your questions. Just reach out and ask!

Since Codeberg uses Forgejo as a base, which itself is a soft-fork of Gitea. Most features that go beyond configuration changes and branding (e.g. the codeberg-light and codeberg-dark themes) should be addressed upstream; all contributions to both Forgejo and Gitea essentially help Codeberg by proxy and are immensely appreciated.

Also check out the Codeberg and Codeberg-Infrastructure organizations, they contain numerous other software and setup projects that will appreciate your contributions.

Working on Codeberg Projects

Running Codeberg means running lots of projects. Later sections of this tutorial will focus on Forgejo, which is one of the most crucial and arguably complex project of Codeberg.

A complete list with all of our projects, as well as their respective maintainers and chatrooms, can be found in our Contributing repository.

Working with Forgejo

Forgejo itself is written in Go. Don't let that intimidate you! Some contributors have made changes to Forgejo and Gitea without having programmed anything in the language beforehand; Go is focused on being a very easy and maintainable language, so you should not get intimidated by it (especially if you have experience with Python or a variant of C already).

Finding issues to work on

The following issue trackers may contain a few ideas for things that could be worked on:

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.

In the Codeberg Community Tracker, there are some issues that are marked using the contribution welcome 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.

Where should I send my patch?

Codeberg has two repositories related to Forgejo:

  • Codeberg-Infrastructure/build-deploy-forgejo: Contains scripts that are used to set up our Codeberg instance
  • Codeberg/forgejo: Forgejo fork that contains branding changes (e.g. themes), hot-fixes for urgent issues (like "dirty" anti-spam measures) and unofficial backports with features or fixes that we find important.

If you have a problem with how Codeberg looks like or if you would like to change something to Codeberg's documentation, you would probably have to submit your change to one of these two repositories.

Alternatively, you should probably send in your patches to Forgejo or Gitea.

We would recommend sending your patches to Forgejo, as it is a project that is heavily associated and works together with Codeberg. Any changes made to Forgejo will land to Codeberg and will also benefit other Forgejo users.

Working with the Forgejo codebase

In order to start working with the Forgejo repository, we would recommend checking out the Forgejo docs and the Gitea docs first.

They provide more detailed and especially more up-to-date information than we could maintain in our own docs. Additionally, there's probably no need for redundancy here 😉.

If you get stuck at any point, Forgejo provides chatrooms that have people that would be willing to help you.

Working with the build-deploy-forgejo repo

This is the deployment system for the Codeberg infrastructure, it updates, builds, configures and deploys Forgejo. If you want to work on new features, please don't use it, but choose our Forgejo fork instead. You shouldn't normally need to bother running build-deploy-forgejo.

The deployment of Codeberg is handled via the Codeberg/build-deploy-forgejo repository. While there's some work on different deployment approaches (more to that later), this is the way stuff is handled as of today. The deployment Makefile connects to a remote server via ssh, so we recommend configuring a virtual machine for this. You can use the provided script or perform the following tasks inside your favourite VM / container solution:

  • Add a user and group git
  • Provide SSH to root
  • Set up a MySQL database forgejo end enter the credentials into your app.ini
  • Install at least git make nodejs npm openssh-server librsvg2-bin (example package names from Debian Buster)
  • Run the Makefile and see that Forgejo is installed, you can override variables and run it like make HOSTNAME_FQDN=localhost deployment
  • After Forgejo is installed, you might want to create an admin user for testing (should otherwise be first user by default), you can use sudo -u git GITEA_WORK_DIR=/data/git GITEA_CUSTOM/etc/gitea /data/git/bin/forgejo admin create-user --username you --admin --password yourpassword --email Please see the deployment repo for the folder structure as well as the upstream docs on how to configure and hack on Forgejo.

Also note that the Makefile will compile Codeberg's Forgejo fork from the codeberg-test branch by default. You can override this behaviour by specifying ORIGIN and GITEA_BRANCH environment to the Makefile.

Working on better deployment methods

If you want to help us improve our deployment scripts, check out the Codeberg-Infrastructure organization. We'd really appreciate moving away from Makefile and shell scripts and ask you to join the discussion there. If you are interested in supporting this project, feel free to contact us. Some legacy resources or WIP might be still invisible to normal users (although we always try to work publicly when possible). Please make sure to first understand what the build-deploy-forgejo repo does to replicate its function. Also feel free to contact us (for example via Matrix) to ask where to help.

Raising an MR to our Forgejo fork

If you fixed an issue specific to Codeberg that should not go into the upstream repo or was refused there, but fits the criteria for our own repo written above, you can file an MR to our own fork of Forgejo. Make sure to point your MR to the codeberg branch and rebase to the latest commits there. Also explain why this should go into the Codeberg repo, if not obvious.

{% admonition "warning" %}

Please note, that the branches may be force-pushed at certain times to make sure the Codeberg commits are well visible and maintainable at any time. This may lead to confusing behaviour of the merge requests, i.e. they seem to include commits you haven't made.

If you face this issue, you can git rebase your commits onto the current Codeberg branch and force-push.

git rebase origin/codeberg
git push -f

{% endadmonition %}

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.

A more comprehensive list of our chatrooms can be found in the Codeberg Matrix Space.

Thank you very much for your interest in improving Codeberg.