# Contributing

Contributions are welcomed, but must follow a simple set of rules in order to
be merged.

**Please follow these conventions if you want your pull request(s) accepted.**

## General

* Try to respect a 80 chars column limit. Not mandatory, but appreciated.
* No trash files. Trash files are by-products of the compilation process, or
  generated files that does not need to be under version control.
* Pull requests must pass the style check. See "Passing the style check" section below.
* Pull requests must compile and work properly.
* Pull requests must pass all tests.
* Pull requests must be mergeable without conflicts.
* Number of commits in a pull request should be kept to one commit and all
  additional commits must be squashed.
* You may have more than one commit in a pull request if the commits are
  separate changes, otherwise squash them.
* Keep your commit messages simple and concise. Good commit messages start
  with a verb ('Add', 'Fix', ...).
* Commit messages should follow the format `topic: message`, e.g. `cli: Added --foo flag`.
  In cases where multiple topics are relevant, use a comma-separated list of topics, e.g.
  `api,float: Fixed printf format specifiers for long double`

## Passing the style check

This project use an automated style checking process for pull requests defined as
an uncrustify configuration file named `.uncrustify.cfg`.

To ease the development process, a pre-commit hook is installable by running
`.githooks/install.sh` from the project root directory. This pre-commit hook
checks for style, outputs a diff of the changes that need to be done, and
produces a patch to fix them automatically.

As the automatic style checker is bound to have errors, parts of the code
that make the checker fail because of their tricky grammar (e.g. Duff devices)
may be enclosed by `/* *INDENT-OFF* */` and `/* *INDENT-ON* */` to disable
the style checker on the region. Note that this feature should be used
*exceptionally*, and that the maintainer will always have the last word regarding
stylistic choices that cannot pass the style check.

## Translations

* You can contribute new translation files for output messages, on the
  condition that you are fluent with the language itself.
* Each correction on existing translations must be followed by a
  rationale ("why would the translation be better if the change is applied?")

## Roadmap

    .
    |- .cmake/: CMake modules
    |- dependencies/: dependencies for building libcriterion
    |- doc/: Sphinx documentation files
    |- dev/: Developer files
    |- include/criterion/: Public API
    |- src/: Sources for libcriterion
    |   |- compat/: Cross-platform abstractions for platform-dependent code
    |   |- core/: Core mechanisms used to run the tests
    |   |- entry/: Entry-point related sources, and default main function
    |   |- io/: IO related functions, redirections
    |   |- log/: Output providers, all the output logic in general
    |   `- string/: String manipulation functions, i18n
    |- po/: Translation files, i18n stuff
    |- test/: Unit tests for libcriterion
    `- samples/: Sample files
        |- outputs/: Expected output files for the current samples
        `- tests/: Internal regression tests
            `- outputs/: Expected output files for the regression tests