Merge pull request #6 from qoherent/community_health

Community health, templates, diagnostics, and CLI

.github/CODE_OF_CONDUCT.md

@@ -1,22 +1,23 @@
-Welcome to RIA Core! We strive to maintain a friendly, respectful, and inclusive community where everyone feels 
-valued and heard. To ensure a positive experience for all contributors, we kindly insist that you adhere to the 
-following guidelines:
+Welcome to RIA Core by Qoherent! 👋
 
-**Be Respectful:** We treat others with kindness, empathy, and respect. 
+We strive to maintain a respectful, inclusive, and collaborative community where everyone feels valued and heard. 
+To ensure a positive experience for all contributors, we kindly insist that you adhere to the following guidelines:
 
-**Be Inclusive:** We welcome diverse perspectives and constructive feedback, but not personal attacks, discrimination, 
-harassment or derogatory language.
+**🌟 Be Respectful:** We believe in treating others with kindness, empathy, and respect. 
+Please keep your interactions and communications civil, and refrain from self-promotion or 
+engaging in any disruptive, unethical, or inappropriate behavior.
 
-**Be Professional:** We maintain professionalism in all our interactions and communications. Please refrain from 
-self-promotion or engaging in disruptive behavior.
+**🌍 Be Inclusive:** We welcome diverse perspectives and constructive feedback, but not personal attacks, discrimination, 
+harassment, or insulting/derogatory language. Please refer to our [Diversity Statement](./DIVERSITY_STATEMENT.md) for 
+additional information regarding our commitment to inclusivity.
 
-**Be Collaborative:** We believe in the power of teamwork and cooperation, support one another, and 
-celebrate each other's successes.
+**🤝 Be Collaborative:** Teamwork makes the dream work! We believe in supporting one another and in celebrating 
+each other's successes.
 
 If you encounter any violations of this code of conduct or witness inappropriate behavior, 
-please report it to [[email protected]]([email protected]) promptly, so we can address the issue.
+please report it to [[email protected]](mailto:[email protected]) promptly, so we can address the issue.
 
 By participating in this project, you agree to abide by this code of conduct. Violations may result in consequences, 
-including but not limited to warnings, temporary or permanent bans, or removal of contributions.
+including but not limited to warnings, temporary or permanent bans, or removal or editing of contributions.
 
-Thank you for helping us maintain a positive and welcoming community! Let's build intelligent radios, together!
+Thank you for helping us maintain a positive and welcoming community! 🙏

.github/CODING.md

@@ -0,0 +1,249 @@
+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]](mailto:[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](./CONTRIBUTING.md) 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](https://github.com/qoherent/michael/discussions/categories/ideas).
+
+### 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](#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](#documentation-guidelines) for more information.
+
+RIA Core's command-line interface (CLI) is powered by [Click](https://click.palletsprojects.com/en/8.1.x/). Each command should be placed in its respective 
+package's `commands.py` file in the `scripts` directory. By applying the `click.command` decorator, the command is 
+automatically integrated into the RIA CLI.
+
+### Python-specific guidelines
+
+We use [Flake8](https://flake8.pycqa.org/en/latest/) for code linting and style enforcement. All Python code must 
+be formatted in accordance with the Flake8 configuration settings defined in the [tox.ini](../tox.ini) file 
+in the root of the project.
+
+To ensure a consistent development environment, this project uses [Poetry](https://python-poetry.org/) for dependency management. 
+[Start here](https://python-poetry.org/docs/basic-usage/) 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](https://docs.python.org/3/glossary.html#term-argument?highlight=keyword%20argument) 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](https://google.github.io/styleguide/cppguide.html).
+
+### Documentation guidelines
+
+We use [Sphinx](https://www.sphinx-doc.org/en/master/) to auto-generate the project's [docs](http://docs.radiointelligence.io/). All docstrings must adhere to the 
+[Sphinx docstring format](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#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](https://peps.python.org/pep-0257/) for further docstring conventions.
+
+### Testing guidelines
+
+We use [Pytest](https://docs.pytest.org/en/8.0.x/) to make our unit testing more efficient and expressive. To run our Pytest test suite:
+
+1. [Activate a Poetry shell](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment), 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](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow). More information can be found in our 
+section on [Our development process](#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](https://www.pauline-vos.nl/atomic-commits/). 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](https://www.sphinx-doc.org/en/master/) to auto-generate the project's [docs](http://docs.radiointelligence.io/). 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](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment), 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:
+```commandline
+make clean
+sphinx-autobuild ./source ./build/html
+```
+
+
+3. A working copy of the docs will now be available at http://localhost:8000/, and any changes made to the source 
+code or configurations will be automatically reflected there.
+
+
+**Important:** if you've added new modules, you may need to execute `sphinx-apidoc -o ./source ../ria` (from 
+within the `docs` directory) and manually update the `index.rst` files to include links to any the new 
+pages. More information on how we use sphinx-apidoc to auto-generate documentation from the docstrings can be 
+found [here](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/build-the-docs.html#generating-documentation-from-docstrings).
+
+
+## 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](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-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](https://github.com/qoherent/ria/discussions/categories/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](./CODE_OF_CONDUCT.md), [Contributing Guidelines](./CONTRIBUTING.md), and the above
+[Coding Guidelines](#coding-guidelines). Additionally, ensure you've reviewed and signed a Contributor License Agreement.
+
+
+2. Ensure that [Python](https://www.python.org/downloads/), [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), and [Poetry](https://python-poetry.org/docs/) are installed on the computer you intend to use for 
+development, and that you're logged into your account on [GitHub](https://github.com/).
+
+
+3. Visit the [RIA Core](https://github.com/qoherent/ria) project on GitHub, and use the [Fork button](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) to create your own copy of the project. 
+
+
+4. Clone down your project fork to your local computer:
+```commandline
+git clone https://github.com/your-username/ria.git
+```
+
+
+5. Add RIA Core as an upstream repository:
+```commandline
+git remote add upstream https://github.com/qoherent/ria.git
+```
+
+
+6. Pull the latest changes from upstream:
+```commandline
+git pull upstream main
+```
+
+
+7. Initialize Poetry from the `pyproject.toml` file at the root of the project:
+```commandline
+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](#initial-setup-for-first-time-contributors) 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.
+```commandline
+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.
+```commandline
+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:
+```commandline
+poetry run pytest
+```
+
+
+4. Confirm your changes are formatted in accordance with our Flake8 style configuration:
+```commandline
+flake8 .
+```
+
+
+5. Ensure that docstrings are properly formatted in the [Sphinx docstring format](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#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](#building-docs) for more information on building, inspecting, and updating the project's docs. 
+
+
+5. 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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-authentication-to-github).
+
+
+### Submit your contribution for review
+
+1. Ensure your changes align with our [Coding Guidelines](#coding-guidelines).
+
+
+2. If your change introduces a deprecation, we ask that you discuss this on the [discussion forum](https://github.com/qoherent/ria/discussions/categories/general) 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](https://github.com/qoherent/ria/discussions/categories/general) 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](https://github.com/qoherent/ria/discussions/categories/general) 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! 🙏💖

.github/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+Thank you for your interest in contributing to RIA Core! 🚀
+
+There are many ways to contribute to the project, including code contributions,
+documentation and tutorial enhancements and translations, providing support in the discussions forum,
+and graphic design.
+
+If you’re unsure where to start or how your skills fit in, please reach out on our [discussion board](https://github.com/qoherent/ria/discussions/categories/general). 
+If you prefer to talk privately, please feel free to email us at [[email protected]](mailto:[email protected]).
+
+Qoherent is dedicated to fostering a friendly, safe, and inclusive environment for everyone. 
+We kindly insist that all contributors review and adhere to our [Code of Conduct](.github/CODE_OF_CONDUCT.md).
+
+
+## Bug reports and feature requests
+
+We value your feedback, are always eager to hear about any issues you encounter or features you'd like to see 
+implemented. Kindly submit bug reports and feature requests via the GitHub issue tracker [here](https://github.com/qoherent/ria/issues).
+
+Upon submission, bug reports and feature requests will be triaged internally by an authorized Qoherent team member
+to confirm alignment with our [Code of Conduct](./CODE_OF_CONDUCT.md) and organizational objectives.
+
+To request features tailored for the specialized needs of your project or research initiative, or that may not align
+with the needs of the general community, please [contact us](https://www.qoherent.ai/contact/) directly. We'd be 
+happy to collaborate with you.
+
+
+## Engaging in the discussions forum
+
+We encourage community engagement in the [discussions forum](https://github.com/qoherent/ria/discussions), especially in the [support channel](https://github.com/qoherent/ria/discussions/categories/support). Engaging 
+in the forum is a great opportunity to learn, meet potential future collaborators, and show off your projects.
+
+Please ensure that your posts and communications align with our [Code of Conduct](./CODE_OF_CONDUCT.md). 
+
+
+## Documentation and tutorial enhancements
+
+We're always excited to welcome contributors to our documentation and tutorial materials. Whether you're passionate 
+about improving docstrings, writing tutorials, crafting how-to guides, providing in-depth explanations, or translating 
+our content into other languages, community contributions play a vital role in enhancing the 
+usability and accessibility of RIA Core.
+
+While company branding and identity graphics, as well as marketing materials, are managed internally, 
+we warmly welcome community contributions of illustrations, diagrams, and visualizations for our documentation 
+and educational materials.
+
+If you are interested in contributing to our documentation and tutorial materials, please reach out on our 
+[discussion forum](https://github.com/qoherent/ria/discussions/categories/general).
+
+
+## Code contributions
+
+All code in this repository, unless otherwise specified, is the exclusive copyright of Qoherent Inc. 
+
+To ensure your protection as a code contributor, as well as the protection of Qoherent and its users, we require all 
+external contributors to sign a Contributor License Agreement (CLA). The CLA does not alter your rights 
+under the [project licence](../LICENSE), but it does transfer the copyright of your contributions to Qoherent Inc. 
+For further details or to complete the CLA, please contact us at [[email protected]](mailto:[email protected]).
+
+Trivial fixes or documentation updates may be accepted without prior submission of a CLA, but we reserve the 
+right and responsibility to reject any changes authored by individuals who have not signed a CLA, or whose 
+authorship we cannot verify.
+
+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.
+
+Since all proposed changes require approval from an authorized Qoherent team member prior to merge, we recommend you
+leave the code review process to us.
+
+For more information on authoring code contributions and to learn about our development process, please 
+refer to our [coding guidelines](./CODING.md).