Skip to content

Latest commit

 

History

History
281 lines (178 loc) · 7.96 KB

CONTRIBUTING.rst

File metadata and controls

281 lines (178 loc) · 7.96 KB

Contributing guidelines

Feature Requests, Bug Reports, and Feedback. . .

. . .should all be reported on the GitHub Issue Tracker .

Reporting issues

Setting-Up environment

Requirements

  1. Having the latest version of git installed locally

  2. Having Python 3.6 installed locally

  3. Having virtualenv installed locally

    To install virtualenv you can run the following command

    $ pip install virtualenv

  4. Having docker and docker-compose installed locally

  5. Having pip environment variables correctly configured

    Some of the package's dependencies of the project could be hosted on a custom PyPi server. In this case you need to set some environment variables in order to make pip inspect the custom pypi server when installing packages.

    To set pip environment variables on a permanent basis you can add the following lines at the end of your \.bashrc file (being careful to replace placeholders)

    # ~/.bashrc

...

# Indicate to pip which pypi server to download from
export PIP_TIMEOUT=60
export PIP_INDEX_URL=<custom_pypi_protocol>://<user>:<password>@<custom_pypi_host>
export PIP_EXTRA_INDEX_URL=https://pypi.python.org/simple

First time setup

  • Clone the project locally

  • Create development environment using Docker or Make

    $ make init

Project organisation

The project

.
├── consensys_utils/           # Main package source scripts (where all functional python scripts are stored)
├── docs/                    # Docs module containing all scripts required by sphinx to build the documentation
├── tests/                   # Tests folder where all test modules are stores
├── .coveragerc              # Configuration file for coverage
├── .gitignore               # List all files pattern excluded from git's tracking
├── .gitlab-ci.yml           # GitLab CI script
├── AUTHORS                  # List of authors of the project
├── CHANGES                  # Changelog listing every changes from a release to another
├── CONTRIBUTING.rst         # Indicate the guidelines that should be respected when contributing on this project
├── LICENSE                  # License of the project
├── Makefile                 # Script implement multiple commands to facilitate developments
├── README.rst               # README.md of your project
├── setup.cfg                # Configuration of extra commands that will be installed on package setup
├── setup.py                 # File used to setup the package
└── tox.ini                  # Configuration file of test suite (it runs test suite in both Python 3.5 and 3.6 environments)

Coding

Development Workflow

Please follow the next workflow when developing

Testing

Running tests

Run test suite in by running

$ make test

Running coverage

Please ensure that all the lines of source code you are writing are covered in your test suite. To generate the coverage report, please run

$ make coverage

Read more about coverage.

Running the full test suite with tox will combine the coverage reports from all runs.

Testing linting

To test if your project is compliant with linting rules run

$ make test-lint

To automatically correct linting errors run

$ make lint

Running full test suite

Run test suite in multiple distinct python environment with following command

$ make tox

Writing documentation

Write clear and exhaustive docstrings in every functional scripts.

This project uses sphinx to build documentations, it requires docs file to be written in .rst format.

To build the documentation, please run

$ make docs

Precisions

Updating changelog

Every implemented modifications on the project from a release to another should be documented in the changelog CHANGES.rst file.

The format used for a release block is be the following

Version <NEW_VERSION>
---------------------

Released on <NEW_VERSION_RELEASED_DATE>, codename <NEW_VERSION_CODENAME>.

Features

- Feature 1
- Feature 2
- Feature 3

Fixes

- Hotfix 1 (``#134``)
- Hotfix 2 (``#139``)

.. _#134: https://github.com/ConsenSys/consensys-utils/issues/134
.. _#139: https://github.com/ConsenSys/consensys-utils/issues/139

Be careful to never touch the header line as well as the release's metadata sentence.

Version <NEW_VERSION>
---------------------

Released on <NEW_VERSION_RELEASED_DATE>, codename <NEW_VERSION_CODENAME>.

Adding a new dependency

When adding a new package dependency it should be added in setup.py file in the install_requires list

The format should be dependency==1.3.2.

When adding a dev dependency (e.g. a testing dependency) it should be added in
  • setup.py file in the extra_requires dev list
  • tox.ini file in the [testenv] deps

Makefile commands

Makefile implements multiple handful shell commands for development

make init

Initialize development environment including
  • venv creation
  • package installation in dev mode

make clean

Clean the package project by removing some files such as .pyc, .pyo, *.egg-info

make test-lint

Check if python scripts are compliant with PEP8 rules

make lint

Automatically correct PEP8 mistakes contained in the project.

make coverage

Run the test suite and computes test coverage. It creates an html report that is automatically open after the commands terminates

make tox

Run the test suites in multiple environments

make docs

Build documentation from the docs folder using sphinx. It generates a build of the documentation in html format located in docs/_build/html.