First off, thank you for taking the time to contribute.
This repository is a docker image wrapping a python Rest API around the aioswitcher pypi module.
If your contribution is a more of a core contribution, please consider maybe it belongs to the integrating module and not the wrapping docker. You can find the module repository here.
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.
container_structure.ymlis the configuration file for GoogleContainerTools container-structure-test validating the container content.
doc8.iniis the configuration file for Doc8 Style Checker checking rst file types.
mypy.iniis the configuration file for MyPy Static Type Checker for checking static types in python scripts.
package.jsonis npm’s package manager file for managing dependencies, scripts and etc.
pyproject.tomlis designated to be the main configuration file for python based on PEP518, not fully operative in this project yet.
.vale.iniis the configuration for vale.
tox.iniis the configuration file for Tox Testing Automation testing the python code.
.dockerignoreused for controlling what goes in the docker image.
.gitignoreused for controlling what will not be pushed to github.
.remarkignoreused for ignoring specific files or folders from remark-lint.
requirements.txtis a list of python requirements constraints.
requirements_prod.txtis a list of python requirements for running the solution.
requirements_docs.txtis a list of python requirements for testing and building the documentation.
requirements_test.txtis a list of python requirements for testing the solution.
package.json file specified by npm manages our dependencies, scripts and some metadata.
docs/sources/vale_stylesis where the vale styles for vale linter are stored. Out of the box, vale comes with three pre-configured plugins: proselint, write-good and joblint. The
docs/sources/vale_styles/docsplugins were manually added from the vale repository.
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.
Some of the steps are considered required and may prevent the PR from being merged. But no worries, everything is fixable.
Requires.io is keeping an eye for versions updates upon the python requirements listed in the
requirements files and in
David-DM is keeping an eye for versions updates upon the npm requirements listed in the package.json file.
When a git-tag with the regex of
/^[0-9.]+$/ is set, Docker Hub Cloud will build the
image based on the
Dockerfile instructions file and tag it twice:
By hook configuration, for every
git-release-tag and push to the
Read the Docs will build the documentation site based on
docs/source and host
it with the following tags:
* stable tag is for the release snapshot.
* latest tag is for the dev branch.
By hook configuration, Read the Docs will build the documentation site based on
and host it:
* stable tag will be built for every release snapshot.
* latest tag will be built for every push the dev branch, so it’ll reflect unreleased changes.
The following (Python, virtualenv, nodeenv and Tox) needs to be pre-installed before local
Python’s virtualenv, a tool for segregating Python environments.
Python’s nodeenv, a tool that enables us to create Node.js virtual environment in resemblance to virtualenv, the tool also allows combining nodeenv inside virtualenv, which is exactly what we’re doing with
Docker, as some of the testing automation are performed within a run-once docker container.
Tox is configured with
To run tox, simply execute
tox.ini’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.)
Please 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
NPM Package: package-json-validator for validating the
Python Module: doc8 for checking restructured text (rst) files residing in
docs/sourceand used to create the documentation site.
doc8 is configured with
Docker Image: jdkato/vale for linting restructured text files residing in
docs/sourcefor spelling/syntax mistakes.
Python Module: sphinx for building the documentation site from the restructured Text (rst) files residing in
NPM Package: markdown-spellcheck for checking the project markdown files for spelling errors.
markdown-spellcheck dictionary file is
Docker Image: koalaman/shellcheck is used for checking shell script residing in
Docker Image: hadolint/hadolint is used for linting the instruction file
Linux Tool: container-structure-test for verifying the docker image content.
The tool runs with the helper script
shellscripts/container-structure-test-verify.sh, it will not fail if the tool is not present when running
toxlocally. But this will probably come up with CircleCi so please consider installing the tool manually.
container-structure-test is configured with
Python Package: flake8 for checking python scripts residing in
Docker Image: circleci/circleci-cli for validating the
Testing is performed with Pytest, Full-featured Python testing tool.
The various Rest Http request test-cases is in
For automated local tests, use
The project’s semvar is being handled in both
VERSION file for creating the docker image
Makefile and in
package.json for packaging handling.
Here are some guidelines (recommendations) for contributing to the
* Code docstrings documentation is here.
If you add a python dependency, for order keeping and for Snyk’s sake, Please add the dependency with the fixed version to
requirements.txt, And add with no version statement in any or all of the other requirements file based on the dependency use case.
If you add a new file, please consider is it should be listed within any or all of the
If you change something inside the
docker imageit is strongly recommended verifying it with the container-structure-test
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 you’re writing python code, please remember to static type your code or else it will probably fail
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-mdwill 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 shell scripts in
shellscripts were written for
bash and not for
bash shellscripts/container-structure-test-verify.shwill verify the existence of container-structure-test and execute it. The script will
exit 0if the tool doesn’t exists so it will not fail
bash shellscripts/push-docker-description.shallows the deployment of the local
README.mdfile as a docker image description in Docker Hub. Please use it with
Makefileas arguments are required.
bash shellscripts/run-once-docker-operations.sh <add-argument-here>will verify the existence of Docker before executing various run-once docker operations based on the following arguments. If the script find that Docker is not installed, it will
exit 0so it will not fail
lint-dockerfilewill execute the docker image hadolint/hadolint linting the local
check-shellscriptswill execute the docker image koalaman/shellcheck for checking the shell scripts residing in
circleci-validatewill execute the docker image circleci/circleci-cli for validating the
vale-rstdocswill execute the docker image jdkato/vale checking for spelling or syntax mistakes in restructured text file residing in
Makefile is highly recommended, especially in regards to docker operations.
make help to list all the available tasks:
make docker-build will build image from relative
make docker-build-testing-imagewill build image from relative
Dockerfileusing a testing tag.
make docker-remove-testing-imagewill remove the testing image (must be build first).
make docker-build-no-cachewill build image from
Dockerfilewith no caching.
make structure-testwill run the container-structure-test tool against the built image (must be build first) using the relative
make docker-build-structure-testwill build the image and test the container structure.
make docker-build-no-cache-structure-testwill build the image and test the container structure.
make docker-full-structure-testing`will build the image with the testing tag and remove after structure test.
make docker-tag-latestwill add latest tag before pushing the latest version.
make docker-runwill run the built image as a container (must be built first).
make docker-build-and-runwill build image from
Dockerfileand run as container.
make docker-build-no-cache-and-runwill build image from
Dockerfilewith no caching and run as container.
make push-descriptionwill push the relative
README.mdfile as full description to docker hub, requires username and password arguments.
make verify-environment-filewill verify the existence of the required environment variables file and its content.
Feel free to join the project’s public Slack Channel. GitHub, Codacy Docker Hub and Snyk are integrated with the channel and keeping its members updated.
This project tries to follow the CII Best Practices guidelines. That’s not an easy task and I’m not sure achieving 100% is even possible for this specific project. At the time writing this, the project has achieved 42%. (The writing of this file was actually according one to those guidelines).
Any contribution bumping up this percentage will be gladly embraced.