# Contribute to Debusine

Contributions to Debusine are greatly appreciated! You can contribute in many ways, be it writing documentation and blog posts, or fixing bugs and implementing new features.

## Join the community

You can reach us using IRC on the #debusine channel at irc.debian.org. That channel is also available as a (bridged) Matrix room. There’s also a #debusine-notifications channel where you can see all activities happening in the GitLab project (it’s also bridged in a Matrix room).

You can also file issues in GitLab’s interface. There are two templates to help you file bug reports and feature requests.

While Freexian is driving the development forward by paying a few developers, rest assured that external contributions are welcome.

## Where to start?

### Starting small

Before starting to work on bigger projects, it probably makes sense to get used to our development workflows by tackling a few small issues (they have the Quick fix label).

### Looking for issues

If you are looking for bigger issues to tackle, you will find plenty in the issue tracker.

The paid developers are usually focused on all the issues planned in the current milestone, working through the list by order of priority (from labels P1 to P3). If you want to help with the current milestone, you should probably start with a low-priority issue.

Otherwise you can also find backlogged issues that are not part of any milestone and that paid developers will not handle at this point.

### Add a new feature

If you want to work on a new feature that is not yet planned, then you should first create a new issue using the `Feature Request` template (see Design new features with issues).

For larger features that require significant design work, it is recommended to first write a development blueprint (see Design new features with development blueprints).

A particular case where we expect and invite contributions is that of new workflows. See Contribute a new workflow for more details of how to go about doing that.

## How to contribute

Note

See runtime environment to understand the runtime environment.

Ready to contribute? Here’s how to set up Debusine for local development:

> 1. Create a guest account on Salsa (a GitLab instance run by the Debian project) by visiting this page: https://salsa.debian.org/users/sign_up

>    Follow all the steps to confirm your email, fill your profile, setup your SSH keys.

>    You might want to have a look at Salsa’s documentation and GitLab’s documentation if you have doubts about something.

>    Note that Debian Developers can skip this step as they already have an account on this service.

> 2. Visit the project’s page and fork Debusine in your own account. See GitLab’s help on how to fork a project.

> 3. Clone Debusine locally:

>        $ git clone git@salsa.debian.org:your-account/debusine.git

>    Note that `your-account` should be replaced by your Salsa’s username. If you want to clone the project without creating any account then use this command:

>        $ git clone https://salsa.debian.org/freexian-team/debusine.git

> 4. For a quick startup, run this command:

>        $ bin/quick-setup.sh

>    It will install required packages with apt and put a sample configuration file in place. It will also create a user and two databases in PostgreSQL. The user will be named after your current Unix user and will own the new databases so that it can connect to the newly created databases without any other authentication.

>    Populate the database with:

>        $ ./manage.py migrate

> 5. Start a local test server:

>        $ ./manage.py runserver
>        [...]
>        Starting development server at http://127.0.0.1:8000/
>        Quit the server with CONTROL-C.

>    Visit the URL returned to have access to the test website.

>    To start also to serve apt repositories, start a second server on port `8081`:

>        $ ./manage.py runserver 8081
>        [...]
>        Starting development server at http://127.0.0.1:8001/
>        Quit the server with CONTROL-C.

> 6. If you want to run tasks, then start the Celery workers, from separate shells:

>        $ python3 -m celery -A debusine.project worker -l INFO -Q scheduler --concurrency 1

>        $ python3 -m celery -A debusine.project worker -l INFO

> 7. You will need to set up a worker:

>        $ mkdir -p ~/.config/debusine/worker
>        $ cat <<EOF > ~/.config/debusine/worker/config.ini
>        [General]
>        api-url = http://localhost:8000/api
>        log-level = DEBUG
>        EOF

> 8. Run the worker with `sbin` dirs in `PATH`, e.g.:

>        $ PATH="/usr/sbin:/sbin:$PATH" LANG=C.UTF-8 python3 -m debusine.worker

> 9. Enable the worker. You can find the name of the worker (by default is the hostname):

>        $ ./manage.py list_workers

>    And then enable it:

>        $ ./manage.py manage_worker enable NAME

> 10. Create a local Django superuser on your test instance:

>         $ ./manage.py createsuperuser

> 11. Login as that user using the link in the top right of the initial REST framework site.

> 12. If you want to use the debusine client, set it up via:

>         $ python3 -m debusine.client setup

>     Set the default workspace to `System`.

> 13. Many of the Debusine worker tasks require an environment, which is a tarball or system image to pass to an executor such as `unshare` or `incus`). You can create one via:

>         $ python3 -m debusine.client work-request create mmdebstrap <<EOF
>           bootstrap_options:
>             architecture: amd64
>             extra_packages:
>             - devscripts
>             variant: minbase
>           bootstrap_repositories:
>           - components:
>             - main
>             mirror: http://deb.debian.org/debian
>             suite: trixie
>         EOF

>     Note that the worker needs the package `mmdebstrap` installed. If the worker does not have the package installed the work request will be in `Pending` and never run. If needed install the package and restart the worker.

>     You can follow the progress (e.g. `Pending`, `Running`, or `Completed`) via the web interface (browse to the scope, then click on the navigation bar for “Work Requests” to see it).

> 14. In order to create workflows or tasks (and also other operations such as creating workflow templates) you will need to give permissions to the user:

> >     $ ./manage.py group create debusine/SystemAdmins
> >     $ ./manage.py workspace grant_role debusine/System owner SystemAdmins
> >     $ ./manage.py group members debusine/SystemAdmins --add YOUR-USER-NAME

> 1. Set up `pre-commit` (optional):

>        $ sudo apt install pre-commit
>        $ pre-commit install

>    This runs some checks every time you run `git commit`. This downloads linters from upstream repositories; if you prefer to avoid that on your development machine, you can skip this step and rely on CI running it for you instead (but with longer latency). See Pre-commit hooks for more details.

> 2. Switch to a new branch:

>        $ git checkout -b name-of-your-bugfix-or-feature

> 3. Develop your new feature, ideally following the rules of Test-Driven Development. Remember to update the release notes as needed.

> 4. When you’re done, check that all tests are succeeding in all supported platforms:

>        $ tox

>    This basically runs `pytest` with multiple versions of Django and Python. It also ensures that you respected our coding conventions. If you get errors, make sure to fix them.

>    Note

>    If you get errors like `OSError: [Errno 38] Function not implemented`, then it means that you are lacking /dev/shm with proper permissions.

> 5. Push your branch to your repository:

>        $ git push -u origin name-of-your-bugfix-or-feature

> 6. Submit us your work, ideally by opening a merge request. You can do this easily by visiting the Debusine project fork hosted in your own account (either through the “Branches” page, or through the “Merge requests” page). See GitLab’s help on merge requests if needed.

>    Make sure to address any issue identified by the continuous integration system, the result of its “pipeline” can be directly seen in the merge request (and in the commits pushed in your own repository).

## Test latest `devel` branch code

If you want to test the code in the `devel` branch, you can install packages from a repository that is automatically generated by our GitLab CI pipeline.

    $ sudo tee /etc/apt/sources.list.d/debusine.sources <<END
    Types: deb
    URIs: https://freexian-team.pages.debian.net/debusine/repository/
    Suites: trixie
    Components: main
    Architectures: all
    Signed-By: |
      -----BEGIN PGP PUBLIC KEY BLOCK-----
      .
      mQENBGUAlgcBCAD0AhJt2KVLlrJ+Bx8VcjxCNGcOEMPOY1Db+F+8TiaYrSqZ07kx
      VOJYATlNAqCkQqCu89E9WvqKTg2kyNZchyArwi4bUhEfA+BT+KBeb4dGcoAdwUNX
      c4hx94M/Ow2hAStIni2TUYau99e5sY2QIFb03Lb3dShlQA2EesjQcvnpZCDBcVHW
      kYGj8zjh+i0QdtGVYJlXI/IskSJKexJuiOQ9uIGtsJ+VAm2hD1dTDWvGoUp2quWP
      uHGBouyzFkFQpCOXKBnfpF4h7LMFJSx9KNV/rSMZgLf0F9ukeGnjsST3okQGz2Sz
      E5WdoJuaLOgj/eCeTG2lHD1sdzyndQtG9sKJABEBAAG0Q0RlYnVzaW5lIFNhbHNh
      IFJlcG9zaXRvcnkgPHJhcGhhZWwrZGVidXNpbmUrc2Fsc2FyZXBvQGZyZWV4aWFu
      LmNvbT6JAU4EEwEKADgWIQSQH9XztPO3VNW3w993YWGYlEiOAAUCZQCWBwIbLwUL
      CQgHAwUVCgkICwUWAgMBAAIeAQIXgAAKCRB3YWGYlEiOAO8eCACwcqdDbVigGiv8
      x9iUOp59/6XMG/mtdSjzkkK5LVUEq9bkQAdLRbzb43p0vLl7E/7Yt3on62D6N3QB
      1ap710QsDRIN/CoKRi6sjHCiAqpSUC9LcwgLmnrLwUHDPDrkpsnWmQ7YINtV1P6E
      BFgdqqtw/1avMyliBbh3/XNRQkYq6xkcEZGIftqwX8GYB3M+cheefYe24H/JwLJm
      gerMz8MVEGKMzDm0OaLjWixV6Ga4Wkzo5ya1zg5OmROULAj3CsKDN76OCEwGGMBs
      kNsTB9aAisP8D6wW6ZXX5eChRLRCmKUEB5zpHJ++jdJ0yY38kF+N17w5eos+rc4s
      bMld2SQP
      =XfKL
      -----END PGP PUBLIC KEY BLOCK-----
    END
    $ sudo apt update

Then run:

    $ sudo apt update
    $ sudo apt install debusine-server debusine-worker debusine-client

And follow the instructions to set up Set up a Debusine server, Set up a Debusine worker or Set up debusine-client.

## Write access to the git repository

Project members have write access to the main git repository. They can thus clone the repository with this URL:

    $ git clone git@salsa.debian.org:freexian-team/debusine.git

From there they can push their changes directly. They are however free to use a fork and request review anyway when they prefer.

## Django Debug Toolbar

Django Debug Toolbar can be used but only on development branches. There are commented out lines in `debusine/project/settings/development.py` and `debusine/project/urls.py` which can be used to add the support.