Thanks for your interest in contributing to this project! We are always happy to receive contributions to the community, whether that be through bug reports, fixes, enhancements, or documentation! This document explains the best practices for contributing to the project.
- Code of Conduct
- Generative AI Policy
- Report an Issue
- Suggest an Enhancement
- Contribute Documentation
- Contribute Code
- Project Style
- Commit Signing
Our first priority is the comfort and safety of our users and contributors. To that end, we have adopted the Contributor Covenant v2.1.
All contributions to the project, including code, documentation, discussions, and others, are subject to the code of conduct. If you witness or are subject to any misconduct covered by our Code of Conduct, please contact a project lead:
- Alexis Shuping: [email protected]
The Code of Conduct can also be found as CODE-OF-CONDUCT.md
Due to concerns about licensing incompatibility, hallucination, and robustness, we do not allow AI-generated content in our project. This applies to code and documentation, and includes suggestions provided by services such as Github Copilot. You may consult with such tools for informational purposes, but please refrain from committing any code or documentation generated by them. We apologize for any inconvenience caused by this policy.
If you run into an issue while using ExSeOS-HLS, please report it so that we can fix it! Issues can be reported on the project repository. Please provide as much detail as possible when reporting your issue, including:
- The steps you took that led to the issue (including code, if relevant)
- What you expected to happen
- What actually happened
- Screenshots of the issue (if relevant)
- Details of your system configuration (OS, python version, etc)
We have a template on github that can help guide you through the steps for submitting a helpful issue!
If you have an idea for an enhancement (either a new feature or an improvement to an existing feature), we'd love to hear it! Please open an issue using the enhancement template, and provide as much detail as possible describing the proposed enhancement.
We always appreciate improvements in our documentation! We use Sphinx to generate documentation.
We welcome improvements and bugfixes! Check the "good first issue" label for issues that we think would be good for new contributors!
Please do take a look at our Project Style for information on how to format and lint your code automatically to conform to the project style.
ExSeOS-HLS follows PEP8 for the most part.
The most notable exception is spacing - for accessibility reasons, we use tabs
rather than spaces. If you personally prefer spaces, this StackOverflow
answer
describes a potential method of setting up your project so that you can work
with spaces on your end and have git automatically perform the conversion to
tabs. You might want to use ruff instead of expand for a cross-platform
solution that will also apply the rest of the project styling on commit!
Note also that, when writing docstrings, it is preferred to put the first line of documentation on the line below the opening quotes, rather than on the same line.
We use Ruff for code linting and formatting. To
check your code, run ruff check. To automatically format your code, run ruff format. Note that certain rules are relaxed for test cases (for example,
preferring def to lambdas).
Plugins are available for several editors to help you fix linting issues as you go. We ask that you lint and format your code before submitting pull requests.
ExSeOS-HLS is built to be as robust as possible. As such, we adopt several conventions that are more typical of Functional Programming than the traditional "pythonic" conventions.
Here are the most important conventions to keep in mind when contributing to the codebase:
- Avoid mutable values whenever practical. If a function acts on an object,
it should return a modified object without touching the original object.
Object parameters should be defined as functions with the
@parameterannotation, to discourage direct modification. - Avoid side effects whenever practical. A function's output should depend only on its inputs, and it should not perform any action beside returning a value.
Of course, these are not hard-and-fast rules. If no function ever performed a side effect, the program wouldn't do anything in the first place. However, minimizing side effects and mutable values makes it much easier to understand what a function does and greatly simplifies the testing process. If you're not sure whether something can / should be done following FP conventions, we have a dedicated section on our forums!
As previously mentioned, we try to make ExSeOS-HLS as robust as possible. Part
of this is a thorough set of tests. We use
pytest for testing purposes, and all of
our test code can be found in the test directory.
We ask that you try to maximize test coverage of any code that you contribute.
We use Codecov to calculate coverage percentage for
commits and pull requests. You can check the coverage locally using pytest:
python -m pytest test --cov-report xml --cov exseos
This will generate an XML coverage report, which can be read by several IDE extensions (for example, Coverage Gutters for VS Code will show the coverage data in the sidebar, making it easy to identify paths without test-case coverage).
It is strongly recommended (but not required) that all contributors set up commit signing.