Skip to content

Latest commit

 

History

History
110 lines (68 loc) · 4.67 KB

CONTRIBUTING.md

File metadata and controls

110 lines (68 loc) · 4.67 KB
Raw

Contributor's Guide

If you're reading this, you're probably looking to contribute to nbcommands. Time is the only real currency, and the fact that you're considering spending some here is very generous of you. Thank you very much!

This document will help you get started with contributing code, testing (future) and filing issues. If you have any questions, feel free to reach out to Vinayak Mehta, the author and maintainer.

Code Of Conduct

The following quote sums up the Code Of Conduct.

Be cordial or be on your way. --Kenneth Reitz

As the Requests Code Of Conduct states, all contributions are welcome, as long as everyone involved is treated with respect.

Your first contribution

A great way to start contributing to nbcommands is to pick an issue with the good first issue label. If you're unable to find a good first issue, feel free to contact the maintainer.

Setting up a development environment

To install the dependencies needed for development, you can use pip:

$ pip install conference-radar[dev]

Alternatively, you can clone the project repository, and install using pip:

$ pip install ".[dev]"

Pull Requests

Submit a pull request

The preferred workflow for contributing to nbcommands is to fork the project repository on GitHub, clone, develop on a branch and then finally submit a pull request. Here are the steps:

  1. Fork the project repository. Click on the ‘Fork’ button near the top of the page. This creates a copy of the code under your account on the GitHub.

  2. Clone your fork of nbcommands from your GitHub account:

$ git clone https://www.github.com/[username]/nbcommands
  1. Create a branch to hold your changes:
$ git checkout -b my-feature

Always branch out from master to work on your contribution. It's good practice to never work on the master branch!

Protip: git stash is a great way to save the work that you haven't committed yet, to move between branches.

  1. Work on your contribution. Add changed files using git add and then git commit them:
$ git add modified_files
$ git commit
  1. Finally, push them to your GitHub fork:
$ git push -u origin my-feature

Now it's time to go to the your fork of nbcommands and create a pull request! You can follow these instructions to do this.

Work on your pull request

It is recommended that your pull request complies with the following rules:

  • Make sure your code follows pep8. You should blacken your code.

  • Make sure your commit messages follow the seven rules of a great git commit message:

    • Separate subject from body with a blank line
    • Limit the subject line to 50 characters
    • Capitalize the subject line
    • Do not end the subject line with a period
    • Use the imperative mood in the subject line
    • Wrap the body at 72 characters
    • Use the body to explain what and why vs. how

  • Please prefix the title of your pull request with [MRG] (Ready for Merge), if the contribution is complete and ready for a detailed review. An incomplete pull request's title should be prefixed with [WIP] (to indicate a work in progress), and changed to [MRG] when it's complete. A good task list in the PR description will ensure that other people get a better idea of what it proposes to do, which will also increase collaboration.

  • If contributing new functionality, make sure that you add a unit test for it, while making sure that all previous tests pass. nbcommands uses pytest for testing (future). Tests can be run using:

$ python setup.py test

Filing Issues

GitHub issues are used to keep track of all issues and pull requests. Before opening an issue (which asks a question or reports a bug), please use GitHub search to look for existing issues (both open and closed) that may be similar.

Bug Reports

In bug reports, make sure you include:

  • Your operating system type and Python version:
import platform; print(platform.platform())
import sys; print('Python', sys.version)
  • The complete traceback. Just adding the exception message or a part of the traceback won't help the maintainer fix your issue sooner.