Getting started
===============

This section is a guide to checking out the source and getting a development
machine configured. More information on development is found in the
:doc:`Developer's guide <developer>`.

Fork the upstream repository
````````````````````````````

The repository at https://github.com/uisautomation/django-boilerplate is configured to
disallow pushing to master. You'll need to *fork* the repository into your
personal account and then open pull requests from your personal repository into
the main repository.

Set up cloud integrations
`````````````````````````

In order to make sure any branches you develop in your fork are tested, visit
the following cloud tool sites, sign in with GitHub and add your new fork:

1. Add your repository to  `Travis CI <https://travis-ci.org/>`_.
2. Go to `Codecov <https://codecov.io/>`_ and add your fork as a watched repo.
   Make sure to enable the Codecov integration.

Clone the repository locally
````````````````````````````

Clone the remote upstream repository locally and configure the push URL to be
your local user fork. This means that ``git push`` commands will modify your
local fork but ``git pull`` commands will automatically fetch from the upstream
repository.

.. code-block:: bash

    $ git clone git@github.com:uisautomation/iar-gatherstats.git
    $ cd iar-gatherstats
    $ git remote set-url origin --push git@github.com:$USER/iar-gatherstats.git

.. note::

    Make sure to replace ``$USER`` with your GitHub user name. If your
    GitHub user name happens to be the same as your local user name, on
    Unix-y systems this will be done by magic!

It is also worth setting up an explicit remote for your personal repository.
Sometimes you'll want to ``push`` or ``pull`` from it.

.. code-block:: bash

    $ git remote add $USER git@github.com:$USER/iar-gatherstats.git

.. _docker-tox:

Running tests
`````````````

The test-suite can be run within the container using a PostgreSQL database in
the following way:

.. code-block:: bash

    $ ./tox.sh

Additional options can be passed to tox by appending them to the command. E.g.

.. code-block:: bash

    $ ./tox.sh -e doc

Output generated by tox is persisted into a volume called "tox-data". See the
docker-compose configuration for the specifics.

Next steps
``````````

See the :doc:`developer` for what to do next.