.. _hacking:

Hacking Coin
============

Make sure the dependencies are installed on the machine you intend to use, see :ref:`admin`.

One important feature is that anyone without a complex setup (e.g. having access to OpenNebula) should be able to work on Coin.
Some parts are hard to work on without access to remote machines of course, but many parts work just fine locally.

Keep in mind to keep patches small, each patch should be atomic, changing only one thing. Tests must pass after the change.

Make sure compilation succeeds::

    make

Fire up your favorite text editor and find the part that interests you.
All code should be covered by unit tests, especially when written in Python.

The `src` directory contains all the source code, in its top-level, the Python parts which provide the basis, such as the scheduler, work items and platform configuration.
One important directory is `src/thrift`. It contains the definitions of all `Thrift datastructures and services <https://thrift.apache.org/>`_. Thrift is the serialization used for almost all RPC in the system.
In `src/www` is the code for the website, the other directories contain mostly Go code.

Running unit tests
^^^^^^^^^^^^^^^^^^

The easiest way is to run all tests for everything::

    make test

This will run Go, Python and Web unit tests.
Usually you'll end up working in only one area though, so running the most relevant unit tests while writing a change is desirable.
When the change seems good, remember to run all tests before asking for reviews.

Go Tests
--------

Running Go tests is fast and there is probably no use running just one of them::

    make gotest

To run an individual test, you need to set the GOPATH environment variable, then run the test with the package name::

    export GOPATH=/path/to/tqtc_coin_ci
    go test agent

Python Tests
------------

For the Python unit tests, you'll have to be in the virtual env to have all dependencies available.
The virtual env is easiest created by running make beforehand::

    source env/bin/activate

Then just run the test that interests you::

    src/test_scheduler.py

Web Tests
---------

To test the UI of the website, run::

    make wwwtest

Both, karma and protractor are run, providing unit and end-to-end tests.

Git Hook
^^^^^^^^

Make sure to follow the instructions in `README-GITHOOK.md` in the Coin repository.
After installing the git hook, you get a sanity check which looks for good formatting and some common bugs.
When you make a commit some tools are run, for Go::

    go vet   # correctness
    go lint  # coding style checker
    go fmt   # checks that code formatting is according to the Go standard

Instead of trying to fix mistakes in the Go formatting, just run::

    make fmt

in the top level directory and your code will be reformatted automatically.

Python::

    ruff  # sanity checking and style guide

Code not following the output of the tools is rejected, some exceptions for rules listed in .ruff.toml.