Colour is open source and we happily welcome contributions. This guide will
give you an overview on how to contribute.

There are many ways to help:

Reporting a defect, proposing a new feature or enhancement or
commenting existing issues on the Issue
Tracker

Contributing new code by implementing new features or adding
examples, for some ideas you can take a look at the issues with the
Enhancement,
Feature
and
Ready
labels or the
v9.9.9
milestone.

Maintaining the existing code base, improving the code style and quality,
improving the coverage, updating the documentation, fixing bugs, addressing
TODOs, etc... Issues with the
Defect
or
Enhancement
labels are a good place to start.

Improving the
Jupyter Notebooks,
we aim to provide a good scientific support to the API and there is still a
lot to do.

Defects

You encountered a problem while using Colour, please consider reporting it
on the Issue Tracker.

The first thing to do, is to check if there are any existing issues describing
your problem, if there is one, you are welcome commenting into it and provide
more details. However, please avoid creating duplicates, they add noise to the
issue tracker and we will have to label them as
Duplicate
and close them.

When reporting a defect please provide the following details if possible and
makes sense to do so:

If you are reporting an exception, please provide the complete traceback, it
will tremendously help us understand what happened.

Features & Enhancements

If you would like a new feature to be supported or an enhancement of an
existing feature, don't hesitate to link any resources or references you feel
like would help its implementation: publications, wikipedia article, etc...

If there is an implementation existing in another language, we will be most
likely be able to port it although the licence must be compatible with the
New BSD License terms.

We are also running Matlab, so
don't hesitate to provide snippets for it if you have functions you would like
to be ported.

Contributing Code

Assuming you have something to work on, you will have to get the code and
follow the guidelines.

Development for Colour

Here is a succinct overview of the steps you will most likely go through:

git checkout -b feature/mie_scattering
The core developers are using the
`git flow branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_
for most of the development tasks and since the branch name appears in the
commit message and for consistency, please use the following branch
prefixes:
- Feature branch prefix: **feature/**
- Release branch prefix: **release/**
- Hotfix branch prefix: **hotfix/**

Check if the unit tests and doctests are running properly.

flake8 is currently set to error if
anything incorrect is found, thus we advice that you run it before
committing and pushing your code to origin, your own fork.

Visit your repository fork on Github. Your branch
should have a green Pull Request button, this will open a pull request
and let us know that we have some code to review :)

Code Reviews

Your pull request will be reviewed by the maintainers and any other developer
interested in the project.

Every single developer has his code reviewed, this is a natural process helping
to raise the codebase quality while having a friendly discussion. Comments will
be made on various aspects such as the documentation and references, the code
style and its implementation. Those can be discouraging, although they are not
meant to criticize but aim at improving the quality of your submission. We all
learn from that process and the project ultimately benefits from them.

Overview

The code has to be PEP 8
compliant although but before anything else, it needs to be consistent with the
Colour Science litterature:

For example, the base CIE colourspace is CIE XYZ with upper case
notation. It can be converted to chromaticity coordinates xy with lower
case notation. If we were to follow the PEP 8
recommendations, we would have written a conversion definition as follows:

defxyz_to_xy(xyz):x,y,z=np.ravel(xyz)x,y=x/(x+y+z),y/(x+y+z)returnx,y

Abstracting the fact the above definition is totally undocumented, it can be
confusing to understand when we are referencing big X tristimulus value or
little x chromaticity coordinate.

For those cases, and there are legions of them in Colour Science, we have
decided to go for clarity and consistency with the literature for the object
names:

defXYZ_to_xy(XYZ):X,Y,Z=np.ravel(XYZ)x,y=X/(X+Y+Z),Y/(X+Y+Z)returnx,y

When the reference is using upper case named variables, we try to follow
the same convention, it is unfortunately not PEP 8
compliant but has the benefit of a much easier comparison between the
implementation and the reference.

Dataset numbers are kept as is if they are from a known reference or
rounded to 15 digits if computed with the API (spectral power
distributions, chromaticity coordinates, etc...).

Unit tests and doctests input numbers are kept as is if they are from
a reference or rounded to 8 digits if computed with the API.

Unit tests output numbers are rounded to 8 digits.

Doctests output numbers trimmed with ellipsis to 7 digits.

Some commonly used dataset elements have aliases like 'cie_2_1931'
for 'CIE 1931 2 Degree Standard Observer'. Those are provided for
convenience and are reserved for external usage, please use the long form
for consistency across the API.

In the same way as above, some computation methods are using a title case
like 'Ohno 2013', while the mapping object holding them is case
insensitive, please use the title case form for consistency across the API.

Some very big lines sometimes cannot be wrapped (doctests, html links), you
can use the # noqa pragma in those cases, although do it in last resort,
we have already too much of them.

Avoid / to wrap lines, prefer using the parenthesis ().

The code formatting is performed using Yapf. You can invoke it recursively on a directory as follows:

find . -type f -name '*.py' -exec yapf -i {}\;

Inline comments must have two spaces.

Ensure that you have blank line at the end of the files.

Ensure that trailing whitespaces are stripped.

Prefix unused variable with an underscore:

_L,a,b=tsplit(Lab)

Citations

It's likely that the code you contribute will be based upon references, we are
using the APA 6th Edition citation style:

We are storing all our citations in a database maintained by
Mendeley.

Commits

A good committing strategy implies that separated commits should be done for
any particular changes: One should not commit multiple bugs fixes or large
change sets at once.

This unnecessarily increase complexity for any code merge or rollbacks needs
and prevent a grainier control over the version control. One exception to this
rule is for the initial design steps when creating a new sub-package or
feature (please consider squashing the commits), but once the said sub-package
is in production, a regular committing strategy should be applied.

Commit messages need to use imperative syntax, the first commit line must be a
quick description of the modification content finished by a punctuation mark
and can be followed by a detailed description separated by one line break. If
the commit fixes a particular issue in the issue tracker, it's advised to state
it in the commit message using the following syntax: Closes #32.

Feature Branches & History

History should never be re-written, although while working on your local
feature branch, you may want to provide a cleaner commits history before
submitting a pull request. It is perfectly fine to modify your local branch
as you wish.

However, if you need to change history on a public and used feature
branch, please inform the Colour developers
in order to avoid commit losses or a merging disaster.

Releasing Colour

The following stages help maintainers navigate through the release of a new
version of Colour: