CODING.md

Qoherent welcomes code contributions from all participants who have signed a Contributor License Agreement (CLA). If you're interested in contributing to our codebase but haven't yet completed a CLA, please reach out to us at [email protected] for more details.

Not a coder? There are many other ways to get involved with the project. Please check out our Contributing Guidelines for additional opportunities and information.

Coding guidelines

To ensure smooth development, reduce frustration, and minimize conflicts, we kindly insist that all code contributions must adhere to these guidelines.

Think there's a better approach? We encourage challenges and discussions to continuously enhance and refine our approach. You're welcome to present your ideas and rationale on our ideas forum.

General guidelines

RIA Core is a Python project. However, we occasionally integrate snippets of C where necessary to enhance performance.

Limit lines to 119 characters. This includes code, comments, docstrings.

All contributions must include appropriate unit tests and doctests. Please refer to our testing guidelines for more information.

All contributions must be well documented, with ample inline comments and with a copious amount of complete docstrings. Please refer to our documentation guidelines for more information.

RIA Core's command-line interface (CLI) is powered by Click. Each command should be placed in its respective package's commands.py file in the ria_cli directory. By applying the click.command decorator, the command is automatically integrated into the RIA CLI.

Python-specific guidelines

We utilize Black for automated code formatting, with configuration settings defined in pyproject.toml. Please ensure that all code contributions are auto-formatted with Black, this is important to ensure consistent and reliably formatted code.

We rely on isort for import sorting, with configuration settings defined in pyproject.toml. Please use isort to automatically organize your import statements.

We use Flake8 for code linting and style. All Python code must be formatted in accordance with the Flake8 configuration settings defined in tox.ini.

To ensure a consistent development environment, this project uses Poetry for dependency management. Start here for information on basic Poetry usage. Please refrain from making unnecessary updates to the poetry.lock file.

RIA Core is a typed project. Please include complete type annotations for all function parameters and return values.

Prefer keyword arguments over positional arguments.

C-specific guidelines

Coming soon: We are still developing our C-specific coding guidelines and the corresponding continuous integration (CI) tests. In the meantime, please format your C code in accordance with Google's C/C++ Style Guide.

Documentation guidelines

We use Sphinx to auto-generate the project's docs. All docstrings must adhere to the Sphinx docstring format.

Types mentioning in the docstring should be expressed in plain English rather than using Python's type hint syntax For example, write "int or float, optional" instead of "Optional[int | float]".

Please refer to PEP-257 for further docstring conventions.

Testing guidelines

We use Pytest to make our unit testing more efficient and expressive. To run our Pytest test suite:

1. Activate a Poetry shell, ensuring that the test dependency group, which includes all the necessary dependencies for running tests, are installed.

2. Run tests with poetry run pytest.

Please include doctests as they provide clear and accessible examples of how to use RIA Core.

Guidelines for Git and GitHub

RIA Core development adheres to the standard Git feature branch workflow. More information can be found in our section on Our development process.

Branch names should begin with the corresponding issue number. For instance, if you are addressing issue #7 regarding README updates, your branch should be named as follows: "7-readme-updates".

Please avoid making changes to the commit history of open pull requests.

Please keep your commits atomic. This makes your changes easier to understand and review.

Please keep your pull requests concise and focused. We recommend limiting your pull requests to around 300 lines.

Building docs

We use Sphinx to auto-generate the project's docs. When making changes, we use sphinx-autobuild to auto-detect these changes. This means you only need to build the docs once, and any changes to the source code or configurations are live-reload in the browser.

1. Activate a Poetry shell, ensuring that the docs dependency group, which includes all the necessary dependencies for building the docs, are installed.

2. Navigate to the docs directory and execute:

make clean
sphinx-autobuild ./source ./build/html

3. A working copy of the docs will now be available at http://localhost:8000/. Any changes made to the configurations in the docs/source directory will be automatically reflected there. Docstring changes will be automatically reflected for all components with corresponding automodule directives.

Important: Upon added new components, ensure to include corresponding automodule directives to the .rst files located in the docs/source directory. This can be done automatically using sphinx-apidoc: simply execute sphinx-apidoc -o ./source ../ria from within the docs directory. Additionally, manually update the index.rst files to include links to any the new pages. More information on how to use sphinx-apidoc to auto-generate documentation from the docstrings can be found here.

Our development process

Contributors develop on their own forked copy of the RIA Core project and propose changes to the upstream project through pull requests.

Proposed changes must pass our suite of CI tests and be approved by an authorized Qoherent team member prior to being merged in to the upstream repository.

If you encounter any issues with our development process, please don't hesitate to reach out for support.

Initial setup for first-time contributors

If you are a first-time contributor, please complete the following steps to initialize your development environment:

1. Please ensure you have reviewed our Code of Conduct, Contributing Guidelines, and the above Coding Guidelines. Additionally, ensure you've reviewed and signed a Contributor License Agreement.

2. Ensure that Python, git, and Poetry are installed on the computer you intend to use for development, and that you're logged into your account on GitHub.

3. Visit the RIA Core project on GitHub, and use the Fork button to create your own copy of the project.

4. Clone down your project fork to your local computer:

git clone https://github.com/your-username/ria.git

5. Add RIA Core as an upstream repository:

git remote add upstream https://github.com/qoherent/ria.git

6. Pull the latest changes from upstream:

git pull upstream main

7. Initialize Poetry from the pyproject.toml file at the root of the project:

poetry init

Give yourself a pat on the back - you're now set up and ready to begin development! 🎉

Author your contribution

Important: First-time contributors should complete the prerequisite setup instructions before starting development. Please do not begin development on any issues until the needs triage 📥 label has been removed. This is to ensure your efforts are focused effectively. We appreciate your patience and understanding.

1. Pull the latest changes from upstream and ensure that your Poetry environment is up-to-date. This is important to ensure you are working off the latest version of the project and to minimize merge conflicts, as well as to maintain a consistent development environment with other contributors.

git pull upstream main
poetry update

2. Create a new local feature branch. It is important to choose a meaningful branch name since it will appear in the merge message. Keep in mind that branch names should start with the corresponding issue number.

git checkout -b \#-my-feature-branch

3. Develop your contribution on your local feature branch, committing regularly as you progress. Don't forget to include tests for and document your code.

4. Ensure all unit tests are passing:

poetry run pytest

4. Confirm your changes are formatted in accordance with our Black, isort, and Flake8 style configurations:

black .
isort .
flake8 .

5. Ensure that docstrings are properly formatted in the Sphinx docstring format and that the Sphinx documentation, which is generated from these docstrings in a semi-automatic manner, looks okay. Please refer to Building docs for more information on building, inspecting, and updating the project's docs.

6. Once you have completed development, all tests are passing, and there are no Flake8 errors or warnings, push your changes to your project fork on GitHub. This will require you to authenticate with GitHub.

Submit your contribution for review

1. Ensure your changes align with our Coding Guidelines.

2. If your change introduces a deprecation, we ask that you discuss this on the discussion forum prior to submitting a pull request.

3. Submit your pull request:

   1. Navigate to your fork on GitHub: https://github.com/your-username/ria.git.
   2. Your new feature branch will show up with a green Pull Request button.
   3. Fill out our pull request template honestly and to the best of your abilities, ensuring that you check all checkboxes. ☑️

4. Your pull request will trigger a suite of CI tests to build and test the code on your branch, as well as to check for code coverage and style issues. If any of these CI tests fail, you will need to make changes.

5. Once your proposed changes pass our suite of automated tests, they will be reviewed by an authorized member of the Qoherent development team, who will provide inline and/or general feedback. If your pull request hasn't been reviewed within a week, please ping us on the discussion forum to ensure it hasn't slipped through the cracks.

6. Once your changes have been approved by an authorized Qoherent team member, we will merge them into the upstream repository. You receive an automated notification from GitHub once your pull request has been merged, at which time the branch containing your changes can then be safely deleted.

7. If your contribution introduces a new feature or significantly alters functionality, we kindly ask that you post on the discussion forum to explain your changes. This is especially important if your changes introduce any user-facing modifications we need to mention in the release notes.

A heartfelt thank you from everyone at Qoherent and the broader radio community for taking the time to contribute to RIA Core. We understand that you're busy and deeply appreciate your time and expertise in helping us in our mission to drive the creation of intelligent radios! 🙏💖