This wiki documents Piksi v2.3.1 which was discontinued April 1st, 2017.
Visit support.swiftnav.com for newer products including Piksi Multi.

Contributor Guidelines

From Swift Navigation Wiki
Jump to navigation Jump to search

Tools

Workflow

  1. Check the issue tracker

    Look on the GitHub issue tracker page. Is there an issue related to your contribution? If not consider creating one so others will know someone is aware of the issue and working on it. The issue page and comment thread are a great places to collect your thoughts on the problem and solution.

    Read more about using the GitHub issue tracker: https://guides.github.com/features/issues/

  2. Create a new feature branch

    Branches are an excellent way to organise your work. When you start a new task or feature you should open a new branch to keep your changes together. You should always be working on a branch and never directly off of master.

  3. Work on your branch

    Try to make frequent commits that contain a single specific change. Ideally the code should build and run between any two commits. Committing often is more important than keeping the history neat at this stage.

  4. Rebase your branch (optional)

    Got your feature working? Great!

    Depending on how much of a mess your branch is in you may want to interactively rebase your branch to tidy up the commit history. This is the point at which to be more picky about having individual commits that contain distinct logical changes with good commit messages. If a particular commit closes a GitHub issue, be sure to reference it. Don't worry about rebasing your local branches or branches you have only pushed to your own GitHub fork but you should never rebase master or anything that has been merged into a public branch. If something has been merged into a public branch it is too late to rebase it now.

  5. Open a pull request

    Once you hare happy with your branch then push it to your own GitHub fork repository. Now open a pull request between that branch and the master branch of the Swift Navigation GitHub account. Opening a pull request will notify the maintainers that your contributions are ready for code review and eventually to be merged into the codebase.

  6. Code review

    The maintainers will comment on your pull request and may ask you to make some changes to your code. Respond to their requests be repeating steps 3 and 4 and then pushing your updates to the existing branch on your GitHub fork (force push if you have to). GitHub will recognise that you have updated your pull request and do the right thing. Please do not open a second pull request. Once the maintainers are happy with your code they will merge it in to the mainstream master branch.

Reviewing code

Coding Style

To help keep our code-base coherent and easy to read and maintain we have adopted a set of coding guidelines. We ask that contributors would read these documents, familiarise themselves with the guidelines and adopt them when submitting contributions to the codebase in order to make life easier for the maintainers.

Any undocumented deviation from these guidelines is a bug and should be reported.

C

For C code we have adopted the Linux Kernel Coding Style, except we use 2 spaces for indentation instead of Tab characters.

https://www.kernel.org/doc/Documentation/CodingStyle

Much of our code is run on embedded systems with an emphasis on reliability and robustness so in addition to stylistic guidelines we have adopted additional guidelines to help reduce the risk of software failures and ensure our code is suitable for running on embedded targets.

For these reasons we have adopted the JPL coding standards:

http://lars-lab.jpl.nasa.gov/JPL_Coding_Standard_C.pdf

Here are a couple of key rules that differ from common practice for non-embedded code:

  • Use integer types with explicitly defined width, we have defined shorthand names for these types in libswiftnav/common.h
    u32, u16, u8, s32 etc.
  • Avoid use of dynamic memory allocation, i.e. no malloc or free
  • Try to keep control flow and logic simple, e.g. no goto etc.

Python

For Python we adopt PEP-8 but again with 2 spaces instead of 4 spaces.

http://www.python.org/dev/peps/pep-0008