Operating system support¶

MCL has been developed in the GNU/Linux operating system. In particular, Debian based systems have been used. As a result, support for Windows and Mac OS X and other Unix systems have not been tested. Due to Python’s flexibility, MCL is likely to work on these platforms with a little more (undocumented) effort.

Obtaining the code¶

MCL can be checked out from the git repository using

git clone https://github.com/acfr/mcl <target>

where <target> is your local target directory.

Installation¶

This code supports installation using pip (via setuptools). To install from the cloned repository:

cd <target>
sudo pip install .

To uninstall the package:

pip uninstall mcl

Documentation¶

The MCL documentation can be read online. To build a local copy run:

cd <target>
make docs

The entry point of the documentation can then be found at:

<target>/doc/build/html/index.html

During compilation, Sphinx’ will attempt to apply the `Read the Docs theme. If this theme is not available, the default Sphinx theme will be used. To enable the Read the Docs theme, install the package via pip:

sudo pip install sphinx_rtd_theme

Identify Yourself¶

If you are contributing to the code base, make sure your contact details have been correctly setup. Do not use an obscure identity in the MCL repositories - this will make it difficult to associate code changes with a contributor. An email address which identifies the author is ideal. This can be done by issuing

git config user.email "<name>@<domain>.com"

in the root of the repository or system wide for all repositories

git config user.email --global "<name>@<domain>.com"

Commit Workflow¶

When committing code to the MCL repository, good commit hygiene ensures that collaborators can monitor changes to the code base. Some guidelines for good development practise are:

• Development including bug fixes and new features should be developed on a local branch based on ‘master’ (in general).
• Make separate commits for logically separate changes. To reduce the amount of “patch noise”, do not submit trivial or minor changes.
• The MCL project favours rebase rather than merge commits on the master branch. A clean linear history of code changes is preferred over traceability of development branches. Never abuse the rebase command to modify the history of commits that have been pushed into a public repository (the same goes for git commit --amend and git reset).

The following is an example of development adhering to this work-flow

1. Get latest changes using:

   git checkout master
   git fetch origin
   git merge master
   

   or

   git checkout master
   git pull origin master
   

2. Isolate development of feature (or bug fix) on a new branch:

   git checkout -b newfeature
   

3. Work on feature

4. Import commits from the remote repository and integrate with the feature branch:

   git fetch origin
   git rebase origin/master
   

5. Repeat steps 3 & 4 until development has completed. Be sure to finalise development by completing step 4 before attempting to integrate your changes with the remote repository.

6. Integrate changes with the remote repository:

   git checkout master
   git pull
   git rebase newfeature
   

   To interactively edit the sequence of commits on the feature branch which are about to be rebased use:

   git rebase -i newfeature
   

   Finally,

   git push
   

Commit Logs¶

Good commit hygiene also includes how commit messages are create. A good commit message will effectively communicate your changes to collaborators. Concise yet descriptive messages are important when viewing the commit history. Good commit messages contain:

1. A short description (soft limit of 50 characters) of the commit on the first line.

   • The first line should not be terminated by a full stop.

   • The first line is often prefixed with the main location of development. For example:

     network: read multiple items from IPv6, UDP socket
     

2. A blank line

3. A more detailed description of the commit wrapped to 72 characters.

An example of a good commit message is included from the git documentation:

Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded by a
   single space, with blank lines in between, but conventions vary here

Code¶

The coding convention adopted in the standard library of the main Python distribution is defined in PEP8: the Style Guide for Python Code. PEP8 warns:

A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important.

In short, when writing new code, take a few minutes to determine the style of the surrounding code. When contributing to the code base, attempt to ‘blend in’ and be consistent with its style.

Python is the main scripting language used at Google. The Google Python Style Guide largely complements PEP8. When in doubt, adopt the style of the surrounding code or defer to PEP8.

pip install pep8
pip install --upgrade pep8
pip uninstall pep8

sudo apt-get install pylint

Documentation¶