Development Guide
=================

Contribution guidelines
-----------------------

Before you submit a pull request to fegistry, please ensure that it meets these criteria:

* All tests must pass.
* Code should have 100% test coverage. This one is particularly important, as we don't want to
  deploy any broken code into production.
* 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).
* Code should follow `PEP-8 <https://www.python.org/dev/peps/pep-0008>`_. You can use the
  ``flake8`` utility to automatically check your code. There is a
  ``fegistry.tests.test_style.TestStyle.test_code_with_flake8`` test, which enforced PEP-8 on the
  codebase.


Development environment
-----------------------

`Vagrant <https://www.vagrantup.com>`_ allows contributors to get quickly up and running with a
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 fegistry checkout is your shell's cwd
    $ vagrant up

fegistry is now running in the guest, and port 5000 has been forwarded on your host::

    $ curl -i http://localhost:5000/v2/
	HTTP/1.0 200 OK
	Content-Type: application/json
	Content-Length: 2
	Docker-Distribution-API-Version: registry/2.0
	Server: Werkzeug/0.11.10 Python/3.5.2
	Date: Thu, 15 Dec 2016 22:04:33 GMT

	{}

You can use ``vagrant ssh`` to ssh into the guest if you like. Inside the guest environment, you
will find the code shared at ``/home/vagrant/fegistry``. There are some convenient bash aliases::

    flog:     Display the development server's log. You can pass a ``-f`` flag to continuously
              display the log.
    frestart: Restart the development server. The development server does automatically pick up
              code changes, so you shouldn't need this much.
    fstart:   Start the development server.
    fstop:    Stop the development server.
    ftest:    Run the test suite.


``vagrant ssh`` also accepts a ``-c`` flag that allows you to run a command in the guest. For
example, you can run the tests wtih ``vagrant ssh -c ftest``.

When you are done with your Vagrant guest, you can destroy it permanently by running this command on
the host::

    $ vagrant destroy