Skip to content

Latest commit

 

History

History
68 lines (43 loc) · 4.21 KB

CONTRIBUTING.md

File metadata and controls

68 lines (43 loc) · 4.21 KB

Contributing

Welcome to the FlowCept project! To make sure new contributions align well with the project, following there are some guidelines to help you create code that fits right in. Following them increases the chances of your contributions being merged smoothly.

Code Linting and Formatting

All Python code in the FlowCept package should adhere to the PEP 8 style guide. All linting and formatting checks should be performed with Ruff. Configuration for Ruff is defined in the pyproject.toml file. The commands shown below will run the Ruff linter and formatter checks on the source directory:

ruff check src
ruff format --check src

Documentation

Sphinx along with the Furo theme are used to generate documentation for the project. The docs optional dependencies are needed to build the documentation on your local machine. Sphinx uses docstrings from the source code to build the API documentation. These docstrings should adhere to the NumPy docstring conventions. The commands shown below will build the documentation using Sphinx:

cd docs
make html

Branches and Pull Requests

There are two protected branches in this project: dev and main. This means that these two branches should be as stable as possible, especially the main branch. PRs to them should be peer-reviewed.

The main branch always has the latest working version of FlowCept, with a tagged release published to PyPI.

The dev branch may be ahead of main while new features are being implemented. Feature branches should be pull requested to the dev branch. Pull requests into the main branch should always be made from the dev branch and be merged when the developers agree it is time to do so.

Issue Labels

When a new issue is created a priority label should be added indicating how important the issue is.

  • priority:low - syntactic sugar, or addressing small amounts of technical debt or non-essential features
  • priority:medium - is important to the completion of the milestone but does not require immediate attention
  • priority:high - is essential to the completion of a milestone

CI/CD Pipeline

Automated versioning

FlowCept follows semantic versioning. There is a GitHub Action that automatically bumps the patch number of the version at PRs to the main branch and uploads the package to PyPI.

Automated tests and code format check

All human-triggered commits to any branch will launch the automated tests GitHub Action. PRs into dev or main will also trigger the code linter and formatter checks, using Ruff.

Automated releases

All commits to the main branch will launch the automated publish and release GitHub Action. This will create a tagged release and publish the package to PyPI.

Checklist for Creating a new FlowCept adapter

  1. Create a new package directory under flowcept/flowceptor/plugins
  2. Create a new class that inherits from BaseInterceptor, and consider implementing the abstract methods:
    • Observe
    • Intercept
    • Callback
    • Prepare_task_msg

See the existing plugins for a reference.

  1. [Optional] You may need extra classes, such as local state manager (we provide a generic Interceptor State Manager), @dataclasses, Data Access Objects (DAOs), and event handlers.
  2. Create a new entry in the settings.yaml file and in the Settings factory
  3. Create a new entry in the pyproject.toml file under the [project.optional-dependencies] section and adjust the rest of the file accordingly.
  4. [Optional] Add a new constant to vocabulary.py.
  5. [Optional] Adjust flowcept.init.py.