Skip to content
This repository has been archived by the owner on Oct 21, 2022. It is now read-only.

Latest commit

 

History

History
224 lines (168 loc) · 8.61 KB

CONTRIBUTING.md

File metadata and controls

224 lines (168 loc) · 8.61 KB

How To Contribute1

First off, thank you for considering contributing to sliphy! 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

NOTE: For local development environment we need python & npm/npx installed in your system.

When python/npm is installed in your system then 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 sliphy repository by forking this repo:

$ git clone [email protected]:<your-username>/sliphy.git

or if you want to use git via https:

$ git clone https://github.com/<your-username>/sliphy.git

Change into the newly created sliphy directory and after activating your virtual environment run,

(.venv) $ pip install -r requirements.txt # assuming that your virtual environment name is .venv

Then go to Sliphy directory and copy .env.example to .env then add values to DJANGO_SECRET_KEY (can be generated using Djecrety) and to DJANGO_DEBUG.

After copying env file go back to root directory and run,

(.venv) $ python manage.py migrate # this will create db tables in your sqlite db
(.venv) $ python manage.py createsuperuser # this will create a super user to access all the things
(.venv) $ python manage.py tailwind install # we're using tailwind css for UI, this command will install dependencies
(.venv) $ python manage.py tailwind start # this command will generate css files, and start filewatcher for tailwind specific files

Open another shell or terminal in your favourite editor, and run

(.venv) $ python manage.py runserver # this will start django server

Now server is up and running you can check out the UI and other things.

To make changes in the codebase,

  • Create a branch for local development 
    (.venv) $ git checkout -b name-of-your-bugfix-or-feature
  • Now you can make your changes locally.
  • Commit your changes and push your branch to GitHub: 
    (.venv) $ git add .
(.venv) $ git commit -m "Your detailed description of your changes."
(.venv) $ 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 sliphy!

1: This contribution guide has been taken from interrogate.