From 9a45e40f3f9f70369413d8ae9ad812ab996e9182 Mon Sep 17 00:00:00 2001 From: Dimitrios Dedoussis Date: Sun, 23 May 2021 13:05:12 +0100 Subject: [PATCH 01/10] docs: add cotribution guidelines #19 --- CONTRIBUTING.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..bcd2a87 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,146 @@ +# Contributing + +Asynction is still at an early beta stage and any contribution towards improving the framework would be greatly appreciated. + +The current areas of focus are: + +* Productionizing the library +* Documentation + +## Table of Contents 📖 + +1. [Roadmap](#roadmap) +1. [Support questions & reporting bugs](#support-questions-&-reporting-bugs) +1. [Development](#development) + 1. [Project structure](#project-structure) + 1. [Environment setup](#environment-setup) + 1. [Coding style](#coding-style) + 1. [Checks & Testing](#checks-&-testing) + 1. [Docs](#docs) +1. [Release](#release) +1. [Finally](#finally) + +## Roadmap + +* Documenting examples and tutorials of using Asynction. +* Improving the generated documentation. +* Exposing an [AsyncAPI playground](https://playground.asyncapi.io/) via a Flask route, in a similar manner to how Connexion exposes a Swagger UI. +* Type casting: Whenever possible Asynction should try to parse the argument values and do type casting to the related Python natives values. +* Dynamic rendering of the [AsyncAPI](https://www.asyncapi.com/) spec. Could use [Jinja2](https://jinja.palletsprojects.com/en/3.0.x/) to allow the parametrisation of the spec. +* Mock server support. +* Authentication à la [Connexion](https://connexion.readthedocs.io/en/latest/security.html). + +The OpenAPI counterparts of Asynction are [Connexion](https://github.com/zalando/connexion) for python and [openapi-backend](https://github.com/anttiviljami/openapi-backend) for Node.js. These tools provide a great source of inspiration for the above roadmap. + + +If you have any roadmap ideas or feature requests please submit them via the [issue tracker](https://github.com/dedoussis/asynction/issues). + +## Support questions & reporting bugs + +You are welcome to use the [issue tracker](https://github.com/dedoussis/asynction/issues) of this repository for questions about using Asynction. Make sure that the `question` label is applied. + +Reporting a bug should also go through the [issue tracker](https://github.com/dedoussis/asynction/issues). + +### Project structure + +``` +root/ +├───asynction/ +├───docs/ +├───tests/ +├───Makefile +├───requirements-dev.txt +├───requirements-test.txt +├───requirements.txt +└───... +``` + +* The `asynction` directory is a python package that contains the runtime source of the framework. +* `docs` is the source directory of the [Sphinx](https://www.sphinx-doc.org/) documentation hosted at . +* `tests` is the source of the entire test suite. +* The top level `Makefile` is a toolbox of useful commands for installing dependencies as well as testing, linting and packaging the code. It is also used as the entrypoint interface for all CI/CD operations. + +### Environment setup + +Use python3.7 or higher. + +1. [Create and activate a virtual environment](https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments) + +1. Upgrade pip and setuptools + + ```bash + $ python -m pip install --upgrade pip setuptools + ``` + +1. Install all the requirements + + ```bash + $ make all-install + ``` + + or install a subset of the requirements depending on the task + + ```bash + $ make requirements-dev-install # Dependecies useful for local development + $ make requirements-test-install # Testing dependencies + $ make requirements-install # Runtime dependencies + ``` + +1. Install the pre-commit hooks + + ```bash + $ precommit install + ``` + +### Coding style + +* All Python code must follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) guidelines. +* Type annotations are mandatory (even in tests). Avoid the use of `typing.Any` or `# type: ignore`. +* All parts of the public API (exposed via `asynction.__init__.py`) should be documented with docstrings. + +__Make sure you run `precommit` before every commit!__ + +### Checks & Testing + +```bash +$ make lint # Checks for flake8 linting, black formatting, and sorting imports (isort) +$ make typecheck # mypy checks + +$ make test-unit # unit testing suite +$ make test-integration # integration testing suite +``` + +### Docs + +There is a [Sphynx](https://www.sphinx-doc.org/) setup located at `/docs`. + +From the root directory: + +```bash +$ make requirements-dev-install # To build the docs, you first need to have the dev dependencies installed. +$ make docs/html +``` + +Open `docs/_build/html/index.html` in your browser to view the generated documentation. + +## Release + +Asynction releases are driven by git tags and [GitHub releases](https://docs.github.com/en/github/administering-a-repository/releasing-projects-on-github/managing-releases-in-a-repository). + +The cut of a git tag will trigger a release workflow. Note that tagging should follow the [SemVer](https://semver.org/) specification. + +The release workflow: + +1. Builds the source and wheel distributions +1. Builds the Sphynx documentation +1. Publishes the distributions to +1. Publishes the distributions to +1. Publishes the HTML docs to + +A changedlog can be found in the [releases](https://github.com/dedoussis/asynction/releases) section of the repository. + +The changelog is autogenerated using the [release-drafter GitHub Action](https://github.com/marketplace/actions/release-drafter). + +## Finally + +Thank you for considering contributing to Asynction ❤️ From 268f0d7e60f4fbc67f42d48b68992c8b5cce937c Mon Sep 17 00:00:00 2001 From: Dimitrios Dedoussis Date: Sun, 23 May 2021 13:10:50 +0100 Subject: [PATCH 02/10] Use correct github link references --- CONTRIBUTING.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bcd2a87..f60f086 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,12 +10,12 @@ The current areas of focus are: ## Table of Contents 📖 1. [Roadmap](#roadmap) -1. [Support questions & reporting bugs](#support-questions-&-reporting-bugs) +1. [Support questions & reporting bugs](#support-questions--reporting-bugs) 1. [Development](#development) 1. [Project structure](#project-structure) 1. [Environment setup](#environment-setup) 1. [Coding style](#coding-style) - 1. [Checks & Testing](#checks-&-testing) + 1. [Checks & Testing](#checks--testing) 1. [Docs](#docs) 1. [Release](#release) 1. [Finally](#finally) @@ -25,14 +25,13 @@ The current areas of focus are: * Documenting examples and tutorials of using Asynction. * Improving the generated documentation. * Exposing an [AsyncAPI playground](https://playground.asyncapi.io/) via a Flask route, in a similar manner to how Connexion exposes a Swagger UI. -* Type casting: Whenever possible Asynction should try to parse the argument values and do type casting to the related Python natives values. +* Type casting: Whenever possible Asynction should try to parse the argument values and do type casting to the related Python native values. * Dynamic rendering of the [AsyncAPI](https://www.asyncapi.com/) spec. Could use [Jinja2](https://jinja.palletsprojects.com/en/3.0.x/) to allow the parametrisation of the spec. * Mock server support. * Authentication à la [Connexion](https://connexion.readthedocs.io/en/latest/security.html). The OpenAPI counterparts of Asynction are [Connexion](https://github.com/zalando/connexion) for python and [openapi-backend](https://github.com/anttiviljami/openapi-backend) for Node.js. These tools provide a great source of inspiration for the above roadmap. - If you have any roadmap ideas or feature requests please submit them via the [issue tracker](https://github.com/dedoussis/asynction/issues). ## Support questions & reporting bugs @@ -41,6 +40,8 @@ You are welcome to use the [issue tracker](https://github.com/dedoussis/asynctio Reporting a bug should also go through the [issue tracker](https://github.com/dedoussis/asynction/issues). +## Development + ### Project structure ``` From 2c9cc944aacc13dc643bf98b69571810de93948a Mon Sep 17 00:00:00 2001 From: Dimitrios Dedoussis Date: Sun, 23 May 2021 13:16:27 +0100 Subject: [PATCH 03/10] Typo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f60f086..03d0988 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -113,7 +113,7 @@ $ make test-integration # integration testing suite ### Docs -There is a [Sphynx](https://www.sphinx-doc.org/) setup located at `/docs`. +There is a [Sphinx](https://www.sphinx-doc.org/) setup located at `/docs`. From the root directory: From 6305e8ef4ed5ed99caf4f4b1196dce6ffce4edd3 Mon Sep 17 00:00:00 2001 From: Dimitrios Dedoussis Date: Sun, 23 May 2021 13:49:57 +0100 Subject: [PATCH 04/10] Typo no. 2 --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03d0988..74fa3b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -133,7 +133,7 @@ The cut of a git tag will trigger a release workflow. Note that tagging should f The release workflow: 1. Builds the source and wheel distributions -1. Builds the Sphynx documentation +1. Builds the Sphinx documentation 1. Publishes the distributions to 1. Publishes the distributions to 1. Publishes the HTML docs to From 1a1bfbcfd713ccacd8889fe2343276ecca6a759c Mon Sep 17 00:00:00 2001 From: Dimitrios Dedoussis Date: Sun, 23 May 2021 17:17:30 +0100 Subject: [PATCH 05/10] Add e2e testing suite roadmap item --- CONTRIBUTING.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74fa3b3..b974654 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,11 +23,12 @@ The current areas of focus are: ## Roadmap * Documenting examples and tutorials of using Asynction. -* Improving the generated documentation. +* Improving the existing generated documentation. +* Mock server support. * Exposing an [AsyncAPI playground](https://playground.asyncapi.io/) via a Flask route, in a similar manner to how Connexion exposes a Swagger UI. +* E2E testing suite (using a dockerised setup) * Type casting: Whenever possible Asynction should try to parse the argument values and do type casting to the related Python native values. * Dynamic rendering of the [AsyncAPI](https://www.asyncapi.com/) spec. Could use [Jinja2](https://jinja.palletsprojects.com/en/3.0.x/) to allow the parametrisation of the spec. -* Mock server support. * Authentication à la [Connexion](https://connexion.readthedocs.io/en/latest/security.html). The OpenAPI counterparts of Asynction are [Connexion](https://github.com/zalando/connexion) for python and [openapi-backend](https://github.com/anttiviljami/openapi-backend) for Node.js. These tools provide a great source of inspiration for the above roadmap. @@ -49,6 +50,8 @@ root/ ├───asynction/ ├───docs/ ├───tests/ +│ ├───integration/ +│ └───unit/ ├───Makefile ├───requirements-dev.txt ├───requirements-test.txt @@ -58,7 +61,7 @@ root/ * The `asynction` directory is a python package that contains the runtime source of the framework. * `docs` is the source directory of the [Sphinx](https://www.sphinx-doc.org/) documentation hosted at . -* `tests` is the source of the entire test suite. +* `tests` is the source of the entire test suite, consisting of unit and integration tests. * The top level `Makefile` is a toolbox of useful commands for installing dependencies as well as testing, linting and packaging the code. It is also used as the entrypoint interface for all CI/CD operations. ### Environment setup @@ -96,7 +99,7 @@ Use python3.7 or higher. ### Coding style * All Python code must follow the [PEP 8](https://www.python.org/dev/peps/pep-0008/) guidelines. -* Type annotations are mandatory (even in tests). Avoid the use of `typing.Any` or `# type: ignore`. +* Type annotations are mandatory (even in tests). Avoid the use of `typing.Any` and `# type: ignore`. * All parts of the public API (exposed via `asynction.__init__.py`) should be documented with docstrings. __Make sure you run `precommit` before every commit!__ @@ -104,7 +107,7 @@ __Make sure you run `precommit` before every commit!__ ### Checks & Testing ```bash -$ make lint # Checks for flake8 linting, black formatting, and sorting imports (isort) +$ make lint # Checks for flake8 linting, black formatting, and sequence of imports (isort) $ make typecheck # mypy checks $ make test-unit # unit testing suite From 6c216ceab6f04a358425a827a58c4cecc1fc7ab8 Mon Sep 17 00:00:00 2001 From: pedrohbtp Date: Mon, 24 May 2021 14:27:14 +0000 Subject: [PATCH 06/10] build: added docker files to make setup more convenient --- Dockerfile | 8 ++++++++ docker-compose.yml | 13 +++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 Dockerfile create mode 100644 docker-compose.yml diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..00fde4a --- /dev/null +++ b/Dockerfile @@ -0,0 +1,8 @@ +FROM python:3.7 +WORKDIR /usr/app +ADD . /usr/app +RUN python -m pip install --upgrade pip setuptools +RUN make all-install +RUN pre-commit install +# initializes all pre-commit envs +RUN pre-commit \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..4658a97 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,13 @@ +version: "3.9" + +services: + asynction: + image: asynction + volumes: + - .:/usr/app + # use the .git from the container because it + # has pre-commit setup + - /usr/app/.git + build: . + entrypoint: bash + From e6d954db1131d09ad749bfacfecb2f145493191d Mon Sep 17 00:00:00 2001 From: pedrohbtp Date: Mon, 24 May 2021 14:29:29 +0000 Subject: [PATCH 07/10] docs: added instructions for docker setup --- CONTRIBUTING.md | 39 ++++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b974654..f9ffa6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,16 +9,19 @@ The current areas of focus are: ## Table of Contents 📖 -1. [Roadmap](#roadmap) -1. [Support questions & reporting bugs](#support-questions--reporting-bugs) -1. [Development](#development) - 1. [Project structure](#project-structure) - 1. [Environment setup](#environment-setup) - 1. [Coding style](#coding-style) - 1. [Checks & Testing](#checks--testing) - 1. [Docs](#docs) -1. [Release](#release) -1. [Finally](#finally) +- [Contributing](#contributing) + - [Table of Contents 📖](#table-of-contents-) + - [Roadmap](#roadmap) + - [Support questions & reporting bugs](#support-questions--reporting-bugs) + - [Development](#development) + - [Project structure](#project-structure) + - [Environment setup using docker](#environment-setup-using-docker) + - [Environment setup without docker](#environment-setup-without-docker) + - [Coding style](#coding-style) + - [Checks & Testing](#checks--testing) + - [Docs](#docs) + - [Release](#release) + - [Finally](#finally) ## Roadmap @@ -64,7 +67,21 @@ root/ * `tests` is the source of the entire test suite, consisting of unit and integration tests. * The top level `Makefile` is a toolbox of useful commands for installing dependencies as well as testing, linting and packaging the code. It is also used as the entrypoint interface for all CI/CD operations. -### Environment setup + +### Environment setup using docker + +For convenience, you can setup the development environment using the Dockerfile and docker-compose files provided in the repo. + +To set it up, run the command: + +``` bash +docker-compose run asynction +``` + +It will install everything and start the container with bash attached. + +### Environment setup without docker + Use python3.7 or higher. From 01322bb9612543844e87e553d93450573899e1d9 Mon Sep 17 00:00:00 2001 From: pedrohbtp Date: Mon, 24 May 2021 14:43:40 +0000 Subject: [PATCH 08/10] build: only map /hooks from container to host --- docker-compose.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docker-compose.yml b/docker-compose.yml index 4658a97..48a59fb 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -7,7 +7,7 @@ services: - .:/usr/app # use the .git from the container because it # has pre-commit setup - - /usr/app/.git + - /usr/app/.git/hooks build: . entrypoint: bash From 0a45decd1dd8bd9c68d801e5f25cc1bfe7a85819 Mon Sep 17 00:00:00 2001 From: pedrohbtp Date: Mon, 24 May 2021 14:45:49 +0000 Subject: [PATCH 09/10] docs: changed precommit to pre-commit --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9ffa6b..b6678bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -110,7 +110,7 @@ Use python3.7 or higher. 1. Install the pre-commit hooks ```bash - $ precommit install + $ pre-commit install ``` ### Coding style @@ -119,7 +119,7 @@ Use python3.7 or higher. * Type annotations are mandatory (even in tests). Avoid the use of `typing.Any` and `# type: ignore`. * All parts of the public API (exposed via `asynction.__init__.py`) should be documented with docstrings. -__Make sure you run `precommit` before every commit!__ +__Make sure you run `pre-commit` before every commit!__ ### Checks & Testing From 54c679a81b97a44c3018054d8cc7823696549c83 Mon Sep 17 00:00:00 2001 From: pedrohbtp Date: Mon, 24 May 2021 15:12:51 +0000 Subject: [PATCH 10/10] docs: readded bash to pre-commit command --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 610026c..6ee5fc1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,9 +112,9 @@ Use python3.7 or higher. 1. Install the pre-commit hooks - +``` bash $ pre-commit install - +``` ### Coding style