Skip to content

Latest commit

 

History

History
163 lines (115 loc) · 6.27 KB

CONTRIBUTING.md

File metadata and controls

163 lines (115 loc) · 6.27 KB
Raw

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
  2. Support questions & reporting bugs
  3. Development
    1. Project structure
    2. Environment setup
    3. Coding style
    4. Checks & Testing
    5. Docs
  4. Release
  5. Finally

Roadmap

  • Improving the existing generated documentation.
  • Support for Class-Based Namespaces. See the relevant issue.
  • Extend CLI to allow running actual apps (and not just mocks).
  • 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 spec. Could use Jinja2 to allow the parametrisation of the spec.

The OpenAPI counterparts of Asynction are Connexion for python and 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.

Support questions & reporting bugs

You are welcome to use the issue tracker 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.

Development

Project structure

root/
├───asynction/
├───docs/
├───example/
│   ├───client/
│   └───app.py
├───tests/
│   ├───e2e/
│   ├───integration/
│   └───unit/
├───Makefile
├───requirements-dev.txt
├───requirements-mock.txt
├───requirements-test.txt
├───requirements.txt
├───setup.py
└───...
  • The asynction directory is a python package that contains the runtime source of the framework.
  • docs is the source directory of the Sphinx documentation hosted at https://asynction.dedouss.is.
  • example includes the implementation of https://socket.io/demos/chat using Asynction. It also includes a mock implementation of the spec.
  • tests is the source of the entire test suite, consisting of unit, integration and e2e 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

Use python3.7 or higher.

  1. Create and activate a virtual environment

  2. Upgrade pip and setuptools

    $ python -m pip install --upgrade pip setuptools

  3. Install all the requirements

    $ make all-install

    or install a subset of the requirements depending on the task

    $ make requirements-dev-install  # Dependecies useful for local development
$ make requirements-test-install  # Testing dependencies
$ make requirements-install  # Runtime dependencies
$ make requirements-mock-install  # Runtime dependencies needed for the mock server support funcitonality
$ make requirements-cli-install  # Runtime dependencies needed for the CLI

  4. Install the pre-commit hooks

    $ pre-commit install

Coding style

  • All Python code must follow the PEP 8 guidelines.
  • 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 pre-commit before every commit!

Checks & Testing

$ make lint  # Checks for flake8 linting, black formatting, and sequence of imports (isort)
$ make typecheck  # mypy checks

# Static checks on the example/ code:
$ make example/typecheck-server
$ make example/lint-client

$ make test-unit  # unit testing suite
$ make test-integration  # integration testing suite
$ make test-e2e  # end-to-end testing suite -- testing against the example chat application in a dockerised environment

Docs

There is a Sphinx setup located at /docs.

From the root directory:

$ 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.

The cut of a git tag will trigger a release workflow. Note that tagging should follow the SemVer specification.

The release workflow:

  1. Builds the source and wheel distributions
  2. Builds the Sphinx documentation
  3. Builds the CLI docker image
  4. Publishes the distributions to https://test.pypi.org/project/asynction/
  5. Publishes the distributions to https://pypi.org/project/asynction/
  6. Publishes the docker image to https://hub.docker.com/r/dedoussis/asynction
  7. Publishes the HTML docs to https://asynction.dedouss.is

A changedlog can be found in the releases section of the repository.

The changelog is autogenerated using GitHub's automatically generated release notes.

Finally

Thank you for considering contributing to Asynction ❤️