Skip to content

Latest commit

 

History

History
247 lines (184 loc) · 8.45 KB

CONTRIBUTING.md

File metadata and controls

247 lines (184 loc) · 8.45 KB
Raw

How To Contribute1

First off, thank you for considering contributing to drf-user! It's people like you who make it such a great tool for everyone.

This document intends to make contribution more accessible by codifying tribal knowledge and expectations. Don't be afraid to open half-finished PRs, and ask questions if something is unclear!

Workflow

  • No contribution is too small! Please submit as many fixes for typos and grammar bloopers as you can!
  • Try to limit each pull request to one change only.
  • Since we squash on merge, it's up to you how you handle updates to the master branch. Whether you prefer to rebase on master or merge master into your branch, do whatever is more comfortable for you.
  • Always add tests and docs for your code. This is a hard rule; patches with missing tests or documentation will not be merged.
  • Make sure your changes pass our CI. You won't get any feedback until it's green unless you ask for it.
  • Once you've addressed review feedback, make sure to bump the pull request with a short note, so we know you're done.
  • Avoid breaking backwards compatibility.

Code

  • Obey PEP 8, PEP 257, and the Numpydoc Docstring Guide. We have a summary line starting the """ block:

    def foo(var1, var2, *args, long_var_name='hi', **kwargs):
    """Summarize the function in one line.

    Several sentences providing an extended description. Refer to
    variables using back-ticks, e.g. `var`.

    Parameters
    ----------
    var1 : array_like
        Array_like means all those objects -- lists, nested lists, etc. --
        that can be converted to an array.  We can also refer to
        variables like `var1`.
    var2 : int
        The type above can either refer to an actual Python type
        (e.g. ``int``), or describe the type of the variable in more
        detail, e.g. ``(N,) ndarray`` or ``array_like``.
    *args : iterable
        Other arguments.
    long_var_name : {'hi', 'ho'}, optional
        Choices in brackets, default first when optional.
    **kwargs : dict
        Keyword arguments.

    Returns
    -------
    type
        Explanation of anonymous return value of type ``type``.
    describe : type
        Explanation of return value named `describe`.
    out : type
        Explanation of `out`.
    type_without_description

    Raises
    ------
    BadException
        Because you shouldn't have done that.

    Notes
    -----
    Notes about the implementation algorithm (if needed).

    This can have multiple paragraphs.

    You may include some math:

    .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}

    And even use a Greek symbol like :math:`\omega` inline.

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a = [1, 2, 3]
    >>> print([x + 3 for x in a])
    [4, 5, 6]
    >>> print("a\nb")
    a
    b
    """
    # After closing class docstring, there should be one blank line to
    # separate following codes (according to PEP257).
    # But for function, method and module, there should be no blank lines
    # after closing the docstring.

  • We follow reorder_python_imports for sorting our imports. Similar to isort but uses static analysis more, and we follow the Black code style with a line length of 88 characters.

Tests

  • Write your asserts as expected == actual to line them up nicely:
 x = f()

 assert 42 == x.some_attribute
 assert "foo" == x._a_private_attribute

Documentation

Project-related documentation is written in restructuredtext (.rst). GitHub-related project documentation (e.g. this file you're reading, CONTRIBUTING.md) is written in Markdown, as GitHub doesn't support .rst files for some of their features (e.g. automatically picking up the CODE_OF_CONDUCT.md)

  • If you start a new section, add two blank lines before and one blank line after the header, except if two headers follow immediately after each other:

     Last line of previous section.

 Header of New Top Section
 -------------------------

 Header of New Section
 ^^^^^^^^^^^^^^^^^^^^^

 First line of new section.

  • If you add a new feature, demonstrate its awesomeness under usage.rst!

Local Development Environment

First create a virtual environment. It’s out of scope for this document to list all the ways to manage virtual environments in Python, but if you don’t already have a pet way, take some time to look at tools like pyenv-virtualenv, pew, virtualfish, virtualenvwrapper, and pyenv-virtualenvwrapper.

Next, get an up to date checkout of the drf-user repository:

$ git clone git@github.com:101loop/drf-user.git

or if you want to use git via https:

$ git clone https://github.com/101loop/drf-user.git

Change into the newly created directory and after activating your virtual environment install an editable version of drf-user along with its tests, docs requirements and to avoid committing code that violates our style guide, we use pre-commit hooks:

Note : For windows users, please refer this link to install choco here and then use following command to setup make

$ choco install make
(env) $ cd drf-user
(env) $ make install

At this point,

(env) $ make test

should work and pass, as should:

(env) $ cd docs
(env) $ make livehtml

The built documentation can then be found in localhost:8888.

Create a branch for local development:

(env) $ git checkout -b name-of-your-bugfix-or-feature

Now you can make your changes locally.

When you're done making changes, check that your changes pass tests and code style should be aligned with Flake8 and Black:

(env) $ make check

Commit your changes and push your branch to GitHub:

(env) $ git add .
(env) $ git commit -m "Your detailed description of your changes."
(env) $ git push origin name-of-your-bugfix-or-feature

Submit a pull request through the GitHub website.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. Please report any harm to devs [at] 101loop.com for anything you find appropriate.

Thank you for considering contributing to drf-user!

1: This contribution guide has been taken from interrogate.