
Higgins
=======

Higgins is a continuous integration software implemented in Python and
inspired by Jenkins.

It allows to track several repositories and to launch test with
respect to dependencies between them.

Quickstart
==========

After the installation with:

.. code-block:: bash

  pip install higgins

the ``hn`` command should be available. The first step is to go the the
directory where your sources are located and launch:

.. code-block:: bash

  hn init

This will create ad ``.hn`` folder. You can then edit the
``.hn/config.yaml`` file to configure your installation. This file
should look like this:

.. code-block:: yaml

  my_project:  # The name of your project
    path: relative/path/to/project
    repository:
      repo_a: path/to/a  # Give a label for each repository path
      repo_b: path/to/b  # Those path are relative to project path
      repo_c: path/to/c

    test:
      true-test: /usr/bin/true
      false-test: /usr/bin/false

    triage:  # repo_a depends on repo_b ad repo_c
      repo_a:
      - repo_b
      - repo_c

    build:  # Define which commands must be launch for each repo
      repo_a:
      - true-test
      - false-test

Then you can launch:

.. code-block:: bash

   hn trigger

This command check every repository for new changesets. And then:

.. code-block:: bash

   hn build

Which will launch all needed test. To check the result you can start:

.. code-block:: bash

   hn serve

and open http://localhost:5000 to see the results. To avoid to launch
the ``build`` and ``trigger`` commands manually you can pass the
``--monitor`` flag to the ``serve`` command:

.. code-block:: bash

   hn serve --monitor  # check all repos every 10 minutes


Other ways to define tests
==========================

You can associate a list of tests to the same label:


.. code-block:: yaml

    test:
      slow-test:
      - bin/sleep 10
      - bin/sleep 30
      - bin/sleep 40
      fast-test:
      - bin/sleep 1
      - bin/sleep 3
      - bin/sleep 4

You can alos specify a test with a base command that will be called on
a list of files:

.. code-block:: yaml

    test:
      wc-test:
        command: /usr/bin/wc -l
        path: "data/*.txt"
        exclude: "data/foo.*"

Where the path will be understood as relative to the repository
folder. This definition will launch ``/usr/bin/wc -l`` on all files of
the 'data' sub-direcotry that ends with '.txt' and will exclude the
ones starting with 'foo.' (the wildcards are expanded with the glob_
method)

.. _glob: http://docs.python.org/2/library/glob.html?highlight=glob#glob.glob


Project inheritance
===================

If you want to track several projects that shares a similar
configuration, you can define inherits a project from another one with
the ``extend`` key.

.. code-block:: yaml

   project:
     repository: ...
     test: ...
     build: ...

   project.dev:
     extend: project
     path: path/to/dev

   project.prod:
     extend: project
     path: path/to/prod
     build: ...   # override the default build config


In the above example ``project`` will be used as a template for
``project.dev`` and ``project.prod``.  Only the project with a path
will be considered.


Override repositories synchronization
=====================================

By default, higgins will update the repositories by calling ``hg pull
-u`` inside each of them. The ``sync-all`` option allows to override
this behaviour. Please note that this command is called once per
project (at the root of the project) and not inside each repository.

.. code-block:: yaml

   project:
     ...
     sync-all: my_custom_command



Roadmap
=======

- Run tests in parallel (across different projects)
- Provide support for a ``sync-each`` method (that will be run inside
  each repository)
- Support for git
- Allows to choose a default banch (per repository ? per project ?)
