Skip to content

Latest commit

 

History

History
312 lines (235 loc) · 12.5 KB

contributing.rst

File metadata and controls

312 lines (235 loc) · 12.5 KB

Contributing new code

Since git and github are used to version and host the code, one needs to learn to work with both tools.

Suggested Git/Github workflow

A small example of a possible workflow is provided here. This is by no means a complete guide on how to work with Git and Github. The Pro Git book can be a very useful reference, whether one is a beginner or an advanced user.

Working with Git Remotes

First make sure your git remotes are properly set, and if not consult Configuring a remote for a fork or Git Basics - Working with Remotes for more detailed explanations about remotes. The remote names are just conventions but in order to simplify this documentation we'll adopt the conventions. So by convention, upstream should point to the "shared" repository, whereas origin should point to your fork. Use git remote -v to perform the check:

$ git remote -v
origin  [email protected]:<github_username>/HoneyBadgerMPC.git (fetch)
origin  [email protected]:<github_username>/HoneyBadgerMPC.git (push)
upstream        [email protected]:initc3/HoneyBadgerMPC.git (fetch)
upstream        [email protected]:initc3/HoneyBadgerMPC.git (push)

Identify the shared remote branch

What should be the base (remote) branch for your work? In many cases, if not most, it'll be the default dev branch, but in other cases you may need to base your work on some other branch, such as jubjub.

It is convenient to have a local copy of the remote shared branch that you need to work on. As an example, if you need to contribute work to the jubjub branch:

$ git fetch upstream
$ git checkout -b jubjub upstream/jubjub

In order to keep your local copy up-to-date you should periodically sync it with the remote. First switch to the local branch:

$ git fetch upstream
$ git rebase upstream/jubjub jubjub

There are multiple ways to work with remote branches. See https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches for more information.

For a small discussion regarding the differences between rebasing and merging see https://git-scm.com/book/en/v2/Git-Branching-Rebasing#_rebase_vs_merge.

Create a new branch

Create a new branch from the shared remote branch to which you wish to contribute. As an example, say you are working on issue #23 (Implement jubjub elliptic curve MPC programs), then you could create a new branch like so:

$ git checkout -b issue-23-jujub-ec-mpc jubjub

You can name the branch whatever you like, but you may find it useful to choose a meaningful name along with the issue number you are working on.

Do you work, backup, and stay in sync

As you are adding new code, making changes etc you may want to push your work to your remote on Github, as this will serve as a backup:

$ git push origin issue-23-jujub-ec-mpc

In addtion to backing up your work on Github you should stay in sync with the shared remote branch. To do so, periodically fetch and rebase:

$ git fetch upstream
$ git rebase upstream/jubjub issue-23-jujub-ec-mpc

Git commit best practices

It is a good idea to familiarize yourself with good practices for the commits you make when preparing a pull request. A few references are provided here for the time being and as the honeybadgermpc project evolves we'll document good practices that are most relevant to the project.

Signing commits

To sign your commits follow the steps outlined at https://help.github.com/articles/signing-commits/.

Resources

Making a pull request

Once you are done with your work, you have to push it to your remote:

$ git push origin issue-23-jujub-ec-mpc

and then you can make a pull request to merge your work with the shared remote branch that you have based your work on.

Pull requests go through the following checks:

  • unit tests
  • code quality
  • documentation quality
  • code coverage

These checks are performed using Travis CI and Codecov. These checks are there to help keeping the code in good shape and pull requests should ideally pass these 4 checks before being merged.

Ideally, you want your pull request to address one concern, such that you can squash your work into a single commit. An example of a project that uses this approach is google/leveldb.

If you need help to work with the git rebase command, see Github Help About Git rebase.

Tests

A pull request should ideally be accompanied by some tests. Code coverage is checked on Travis CI via codecov. The coverage requirements are defined in the :file:`.codecov.yaml` file. See codecov's documentation on coverage configuration for more information about the codecov.yaml file.

pytest is the framework used to write tests and it is probably a good idea to consult its documentation once in a while to learn new tricks as it may help a lot when writing tests. For instance, learning to work with pytest fixtures can help greatly to simplify tests, and re-use test components throughout the test code.

Interesting resource on writing unit tests:: https://pylonsproject.org/community-unit-testing-guidelines.html

Coding Conventions

PEP 8 is used as a guide for coding conventions. The maximum line length is set at 89 characters.

The flake8 tool is used in the continuous integration phase to check the code quality. The configuration file, .flake8, is under the project root.

Tip

Recommended reading: The Code Style section in the The Hitchhiker’s Guide to Python!.

Documentation Conventions

PEP 257 is used for docstring conventions. The docstrings are extracted out into the documentation with the autodoc Sphinx extension and should be valid reStructuredText. Here's an example of how a function may be documented:

.. todo:: Use a HoneyBadgerMPC code sample instead of sample shown below.


def send_message(sender, recipient, message_body, [priority=1]):
    """Send a message to a recipient

    :param str sender: The person sending the message
    :param str recipient: The recipient of the message
    :param str message_body: The body of the message
    :param priority: The priority of the message, can be a number 1-5
    :type priority: integer or None
    :return: the message id
    :rtype: int
    :raises ValueError: if the message_body exceeds 160 characters
    :raises TypeError: if the message_body is not a basestring
    """

See Sphinx documentation: info field lists, for more information on how to document Python objects.

Tip

Recommended reading: The Documentation section in the The Hitchhiker’s Guide to Python! is a useful resource.

Ignoring conventions

The PEP 8 style guide has a very important section at the beginning: A Foolish Consistency is the Hobgoblin of Little Minds. It says:

One of Guido’s key insights is that code is read much more often than it is written. The guidelines provided here are intended to improve the readability of code and make it consistent across the wide spectrum of Python code. As PEP 20 says, "Readability counts".

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 the most important.

However, know when to be inconsistent—sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don’t hesitate to ask!

So if you need to ignore some convention(s), and doing so make one or more checks fail you can ignore the error inline with the # noqa: <error code> comment. As an example, say you wanted to ignore E221 (multiple spaces before operator) errors:

coin_recvs = [None] * N
aba_recvs  = [None] * N  # noqa: E221
rbc_recvs  = [None] * N  # noqa: E221

See Selecting and Ignoring Violations for more information about ignoring violations reported by flake8.

Error codes

Logging

Make use of the :mod:`logging` module! If you are unsure about whether you should log or print, or when you should log, see When to use logging.

Important resources on logging

Rust bindings

.. todo:: Document important things to know when contributing to this
    component.

References