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.
.circle/config.ymlis the configuration file for CircleCi Continuous Integration and Deployment Services.
.codecov.ymlis the configuration file for CodeCov Code Coverage.
.yamllintis the configuration for yamllint A Linter for YAML Files linting yml files.
bandit.ymlis the configuration file for Bandit common security issues finder checking python scripts.
src/aioswitcheris the Python modules making the package.
testsis where Python test-cases are stored and executed with pytest.
pyscripts`is where Python scripts are stored.
poetry.lockis 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.jsonis 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.txthas 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.pyfrom the content of
poetry.lockfile for legacy support (e.g. Requires-io).
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.
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.
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 is keeping an eye for versions updates upon the Python requirements listed in our
By hook configuration, Read the Docs will build the documentation site based on
and host it:
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.
Tox utilizes Python’s virtualenv.
Tox is configured with
To run tox, simply execute
pyproject.toml’s path. It is recommended that you also run
tox --helpto get familiar with the various options such as
-rthat will help you perform faster and better tests.
The rest of the steps require no installation on your behalf,
but knowing them is important seeing they are key elements for testing with
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
NPM Package: package-json-validator for validating the
NPM Package: markdown-spellcheck for checking the project markdown files for spelling errors.
markdown-spellcheck dictionary file is
Python Module: doc8 for checking restructuredText syntax for files residing in
docs/sourceused to create the documentation site.
Python Module: sphinx for building the documentation site from the restructuredText files residing in
Python Package: flake8 for linting Python files.
Python Package: mypy for checking static typing in Python files.
Python Package: pytest as testing framework for running test-cases written in
Testing is performed with Pytest Full-featured Python testing tool. The various test-cases is
For automated local tests, use Tox.
The project semver is handled in both
Here are some guidelines (recommendations) for contributing to the
* Code docstrings documentation [here](https://aioswitcher.readthedocs.io/en/stable/codedocs.html)
For any change in dependencies, please use
pyscripts/poetry-to-requirements.pyfor creating a valid
requirements.txtfile and add it to your PR. This is also done automatically with the
While not all the test steps in
Toxare parallel to each other, most of them are, so tests failing with
Toxwill probably also fail with
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-interactivefor handling all spelling mistakes before testing. You can also choose to run
spell-md-reportto print a full report instead of handling the spelling mistakes one-by-one. * markdown-spellcheck dictionary is the file
Before using the scrips, you need to install the dependencies.
package.json file path, run
Then you can execute the scripts from the same path.
npm run lint-md will run remark against markdown files.
npm run validate-pkgwill run package-json-validator against the
npm run spell-md-interactivewill run markdown-spellcheck against markdown files in an interactive manner allowing us to select the appropriate action.
npm run spell-md-reportwill run markdown-spellcheck against markdown files and print the report to stdout.
The code of conduct can be found [here](https://aioswitcher.readthedocs.io/en/stable/conduct.html).