=======================
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 should have 100% test coverage. This one is particularly important, as we don't want to
deploy any broken code into production.
* New functions, methods, and classes should have docblocks that explain what the code block is, and
describing any parameters it accepts and what it returns (if anything).
* New code should follow `PEP-8 `_. You can use the
``flake8`` utility to automatically check your code. There is a
``bodhi.tests.test_style.TestStyle.test_code_with_flake8`` test, that is slowly being expanded to
enforce PEP-8 across the codebase.
* Add an entry to ``docs/release_notes.rst`` for any changes you make that should be in release
notes.
* Make sure your commits are atomic. Each commit should focus on one improvement or bug fix. If you
need to build upon changes that are related but aren't atomic, feel free to send more than one
commit in the same pull request.
Create a Bodhi development environment
======================================
There are two ways to bootstrap a Bodhi development environment. You can use Vagrant, or you can use
virtualenv on an existing host.
Vagrant
-------
`Vagrant `_ allows contributors to get quickly up and running with a
Bodhi development environment by automatically configuring a virtual machine. Before you get
started, ensure that your host machine has virtualization extensions enabled in its BIOS so the
guest doesn't go slower than molasses. To get started, simply
use these commands::
$ sudo dnf install ansible libvirt vagrant-libvirt vagrant-sshfs
$ sudo systemctl enable libvirtd
$ sudo systemctl start libvirtd
$ cp Vagrantfile.example Vagrantfile
# Make sure your bodhi checkout is your shell's cwd
$ vagrant up
``Vagrantfile.example`` sets up a port forward from the host machine's port 6543 into the Vagrant
guest's port 6543, so you can now visit http://localhost:6543 with your browser to see your Bodhi
development instance if your browser is on the same host as the Vagrant host. If not, you will need
to connect to port 6543 on your Vagrant host, which is an exercise left for the reader.
Quick tips about the Bodhi Vagrant environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can ssh into your running Vagrant box like this::
# Make sure your bodhi checkout is your shell's cwd
$ vagrant ssh
Once you are inside the development environment, there are a helpful set of commands in your
``.bashrc``:
* ``bdocs``: Build Bodhi's documentation.
* ``blog``: View Bodhi's log.
* ``brestart``: Restart the Bodhi service.
* ``bstart``: Start the Bodhi service.
* ``bstop``: Stop the Bodhi service.
* ``btest``: Run Bodhi's test suite.
Keep in mind that all ``vagrant`` commands should be run with your current working directory set to
your Bodhi checkout. The code from your development host will be mounted in ``/home/vagrant/bodhi``
in the guest. You can edit this code on the host, and the vagrant-sshfs plugin will cause the
changes to automatically be reflected in the guest's ``/home/vagrant/bodhi`` folder.
The development server is run inside the Vagrant environment by the ``bodhi.service`` systemd unit.
You can use ``pshell`` and ``tools/shelldb.py`` to get a Python shell quickly set up with a nice
environment for you to hack in::
[vagrant@localhost bodhi]$ pshell development.ini
Python 2.7.12 (default, Sep 29 2016, 13:30:34)
[GCC 6.2.1 20160916 (Red Hat 6.2.1-2)] on linux2
Type "help" for more information.
Environment:
app The WSGI application.
registry Active Pyramid registry.
request Active request object.
root Root of the default resource tree.
root_factory Default root factory used to create `root`.
Custom Variables:
m bodhi.server.models
t transaction
>>> execfile('tools/shelldb.py')
Once you've run that ``execfile('tools/shelldb.py')`` tools command, it's pretty easy to run
database queries::
>>> db.query(m.Update).filter_by(alias='FEDORA-2016-840ff89708').one().title