Contributing

First off, thank you for taking the time to contribute.

Contributing is pretty straight-forward: * Fork the repository * Commit your changes * Create a pull request against the dev branch

Please feel free to contribute, even to this contributing guideline file, if you see fit.

Items description

Configuration files

Python

  • src/aioswitcher is the Python modules making the package.

  • tests is where Python test-cases are stored and executed with pytest.

  • pyscripts` is where Python scripts are stored.

Requirement files

  • poetry.lock is the lock file describing the module version tree of the pypi modules. This helps locking down working versions of modules, it is part of the poetry dependency management.

  • package-lock.json is the lock file describing the module version tree of the npm modules. This helps locking down working versions of modules, it is part of the npm dependency management.

  • requirements.txt has noting to do directly with the package structure. We use poetry for packaging and building. This file is actually being manually build with pyscripts/poetry-to-requirements.py from the content of poetry.lock file for legacy support (e.g. Requires-io).

Package management

  • The package.json file specified by npm manages our dependencies, scripts and some metadata.

  • The pyproject.toml is the main configuration file for the pypi package based on PEP518. Please note, this package is being managed, build, packaged and deployed with poetry.

Documentation

  • docs/sources is where the restructuredText files for creating the Sphinx Documentation. are stored for build, deployment and hosting by Read the Docs.

  • docs/Makefile the basic Makefile for Sphinx documentation generator. From the docs path, type make html and sphinx will create the documentation site locally in docs/build.

Continuous Integration

CircleCi

By hook configuration, for every pull request, CircleCi will execute the workflows described in .circleci/config.yml and update the PR conversation with the results.

As a final step, CircleCi will push the Coverage.py XML Report to both CodeCov for code coverage analysis and Codacy for code quality analysis.

Both will of course push their results into the PR conversation.

Please note, Codacy is actually getting notified for the PR by a GitHub hook. The report being uploaded is for the dashboard presentation and does not trigger further action.

Some of the steps are considered required and may prevent the PR from being merged. But no worries, everything is fixable.

CodeCov

CodeCov is keeping tabs on our code coverage. When a report is uploaded (by CircleCi), CodeCov will check our code coverage and push its conclusions to PR conversation.

Codacy

Codacy is here to check the quality of our code. When a PR is created or updated, GitHub is hooked to notify Codacy that starts checking the quality of our code and push its conclusions to the PR conversation.

Requires-io

Requires.io is keeping an eye for versions updates upon the Python requirements listed in our legacy requirements.txt file.

David-DM

David-DM is keeping an eye for versions updates upon the Npm requirements listed in the package.json file.

Continuous Deployment

Read the Docs

By hook configuration, Read the Docs will build the documentation site based on docs/source and host it:

PyPI

As for now, I’m not auto-deploying anything to PyPi. Packages are being deployed manually.

Environments and Tools

Note

Python, poetry and Tox needs to be pre-installed.

  • Python, CPython interpreter based, although this package supports Python3.5/3.6/3.7, Python3.7 is preferred.

  • Poetry is being used for packaging and dependency management. * Please install Poetry if you plan on developing or testing the package.

  • Tox for automating unit testing in your local environment. * Please install Tox if you want to perform local testing automation.

    • Tox utilizes Python’s virtualenv.

    • Tox is configured with pyproject.toml.

    • To run tox, simply execute tox from the pyproject.toml’s path. It is recommended that you also run tox --help to get familiar with the various options such as -e and -r that will help you perform faster and better tests.

Note

The rest of the steps require no installation on your behalf, but knowing them is important seeing they are key elements for testing with Tox and/or CircleCi.

  • Python Module: nodeenv, a tool that enables us to create a Node.js virtual environment in resemblance to virtualenv, this tool also allows combining nodeenv within virtualenv, which is exactly what we’re doing with tox.

  • NPM Package: package-json-validator for validating the package.json file.

  • Python Package: yamllint for linting the project yml files. * yamllint is configured with .yamllint.

  • NPM Package: markdown-spellcheck for checking the project markdown files for spelling errors.

  • NPM Package: remark-lint which is a plugin for remark and the remark-cli command line tool for linting markdown files residing at the base path and in .github.

    • remark-lint uses a couple of presets and tools, all can be found under the dependencies key in package.json.

    • remark-lint is configured with .remarkrc.

  • Python Module: doc8 for checking restructuredText syntax for files residing in docs/source used to create the documentation site.

  • Python Module: scspell3k for spell checking restructuredText files residing in docs/source used to create the documentation site. * scspell3k dictionary file is .spelling.

  • Python Module: sphinx for building the documentation site from the restructuredText files residing in docs/source.

  • Python Package: bandit for finding common security issues with against the Python files. * bandit is configured with bandit.yml.

  • Python Package: isort for sorting Python imports. - isort is configured with pyproject.toml.

  • Python Package: flake8 for linting Python files.

  • Python Package: black for formatting Python files. * black is configured with pyproject.toml.

  • Python Package: mypy for checking static typing in Python files.

  • Python Package: pytest as testing framework for running test-cases written in tests.

Testing

Testing is performed with Pytest Full-featured Python testing tool. The various test-cases is in tests.

For automated local tests, use Tox.

Guidelines

Note

The project semver is handled in both pyproject.toml and package.json.

Here are some guidelines (recommendations) for contributing to the aioswitcher project: * Code docstrings documentation [here](https://aioswitcher.readthedocs.io/en/stable/codedocs.html)

  • For any change in dependencies, please use pyscripts/poetry-to-requirements.py for creating a valid requirements.txt file and add it to your PR. This is also done automatically with the py37 testenv in tox.

  • While not all the test steps in CircleCi and in Tox are parallel to each other, most of them are, so tests failing with Tox will probably also fail with CircleCi.

  • If writing Python code, please remember to [static type](https://www.python.org/dev/peps/pep-0484/).

  • You can run npm’s script spell-md-interactive for handling all spelling mistakes before testing. You can also choose to run spell-md-report to print a full report instead of handling the spelling mistakes one-by-one. * markdown-spellcheck dictionary is the file .spelling.

NPM Scripts

Before using the scrips, you need to install the dependencies. From the package.json file path, run npm install, Then you can execute the scripts from the same path. * npm run lint-md will run remark against markdown files.

  • npm run validate-pkg will run package-json-validator against the package.json file.

  • npm run spell-md-interactive will run markdown-spellcheck against markdown files in an interactive manner allowing us to select the appropriate action.

  • npm run spell-md-report will run markdown-spellcheck against markdown files and print the report to stdout.