Developer documentation¶
This page contains information for developers who wish to contribute to Bodhi.
Contribution guidelines¶
Before you submit a pull request to Bodhi, please ensure that it meets these criteria:
All tests must pass.
New code must have 100% test coverage. This one is particularly important, as we don’t want to deploy any broken code into production. At the end of
btest
run, you can see your code coverage. If you are not using BCD environment you can check the code coverage by runningdiff-cover coverage.xml --compare-branch=origin/develop --fail-under=100
.New functions, methods, and classes must have docblocks that explain what the code block is, and describing any parameters it accepts and what it returns (if anything). You can use the
pydocstyle
utility to automatically check your code for this. You can also runpydocstyle /bodhi
in BCD.Parameter and return value types should be declared using type hints.
New code must follow PEP-8. You can use the
flake8
utility to automatically check your code.If you want to run the three above at once you can use
blint
alias in BCD.Make sure your commits are atomic. With only rare exceptions, each improvement or bug fix should have exactly one commit. This makes it much easier to peruse the git history to find out which changes relate to a feature or bugfix implementation, and is particularly valuable when commits need to be cherry picked. If you need to build upon prior unmerged commits while fixing a different issue, feel free to send more than one commit in the same pull request.
Your commit messages must include a Signed-off-by tag with your name and e-mail address, indicating that you agree to the Developer Certificate of Origin. Bodhi uses version 1.1 of the certificate, which reads:
Developer Certificate of Origin Version 1.1 Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 1 Letterman Drive Suite D4700 San Francisco, CA, 94129 Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it. (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
For example, Randy Barlow’s commit messages include this line:
Signed-off-by: Randy Barlow <randy@electronsweatshop.com>
Code may be submitted by opening a pull request at github.com/fedora-infra/bodhi, or you may e-mail a patch to the mailing list.
If your changes contain database migrations, you must add a file named
summary.migration
in thenews
directory, wheresummary
is a short textual description of the change (or the issue number you’re fixing).If it is not present already, add a file in the
news
directory namedusername.author
whereusername
is the first part of your commit’s email address, and containing the name you want to be credited as.If you think that the changes you make should be in release notes, add a file in the
news
directory with the format explained below.
Release Notes¶
To add entries to the release notes, create a file in the news
directory in the
source.type
name format, where the source
part of the filename is:
42
when the change is described in issue42
PR42
when the change has been implemented in pull request42
, and there is no associated issueCabcdef
when the change has been implemented in changesetabcdef
, and there is no associated issue or pull request.
And where the extension type
is one of:
bic
: for backwards incompatible changesdependency
: for dependency changesfeature
: for new featuresbug
: for bug fixesdev
: for development improvementsdocs
: for documentation improvementsother
: for other changes
The content of the file will end up in the release notes. It should not end with a .
(full stop). A preview of the release notes can be generated with towncrier --draft
.
Issues¶
Bodhi uses GitHub’s issue tracker and kanban boards to track and plan issues and work. If you aren’t sure what you’d like to work on, take a look at Bodhi’s labels which are used to categorize the various issues. Each label has a short description explaining its purpose.
Easy Fix¶
If you are looking for some easy tasks to get started with Bodhi development, have a look at Bodhi’s EasyFix tickets.
CI Tests¶
All Bodhi pull requests are tested in Github Actions.
Sometimes tests fail, and when they do you can visit the test job that failed by clicking the
Details link next to it in the report that appears on the pull request page. Links to individual pull request
builds can be found on your pull request on GitHub by clicking the “Details” link next to
continuous-integration/jenkins/pr-merge
. From there you can inspect the full console output, or
you can click into the “Pipeline Steps” on the left to see the output of each individual job.
Bodhi’s CI pipeline workflow is described in the Github Actions workflow files in
.github/workflows
. These files describe to Github how it should run Bodhi’s tests. If you are
not familiar with Github Actions, please refer to the extensive upstream documentation.
It is possible for you to run these same tests locally. There is a devel/ci/bodhi-ci
script
that is used by the pipeline to do the heavy lifting. This script is intended to be
run as root since it uses docker
(or optionally, podman
). It has a handy -x
flag that
will cause it to exit immediately upon failure. You can also choose to test specific releases, and
there are a variety of other features. Be sure to check out its --help
flag to learn how to use
it. Thus, if I want to run the tests on only f28 and f29 and I want it to exit immediately upon
failure, I can execute the script like this:
$ sudo devel/ci/bodhi-ci all -r f28 -r f29 -x
Create a Bodhi development environment¶
You can use Bodhi’s “BCD” container-based development environment. Using Vagrant or a local Python virtualenv are no longer supported. See the BCD Guide for instructions on using BCD.
You can configure Visual Studio Code to run unit-tests inside with Bodhi BCD - VS Code Guide.