Welcome! Thank you for your interest in contributing to this project. There are many ways to contribute, including submitting bug reports, improving documentation, submitting feature requests, reviewing new submissions, or contributing code that can be incorporated into the project.
This document describes this project's development process. Following these guidelines shows that you respect the time and effort of those managing this project. In return, you will be shown respect in addressing your issue, reviewing your changes, and incorporating your contributions.
Note Please, don't use the issue tracker for support questions. Instead use: Github Discussions.
Table of Contents:
- Important Resources
- Finding an Issue
- Reporting Bugs
- Feature Requests
- Improving Documentation
- Development Process
- Contributing Code
- Pull Request Process
TODO
The list of outstanding feature requests and bugs can be found on our on our GitHub issue tracker. Pick an unassigned issue that you think you can accomplish and add a comment that you are attempting to do it.
Regarding issue labels:
good first issuelabeled issues are deemed to be good low-hanging fruit for newcomers to the project.help-wantedlabeled issues may be more difficult and may include new feature development.type:documentationlabeled issues must only touch content in thedocsfolder.
Note If you find a security vulnerability, do NOT open an issue. Please refer to our Security Policy for reporting security vulnerabilities.
Before you submit your issue, please search the issue archive - maybe your question or issue has already been identified or addressed.
If you find a bug in the source code, you can help us by submitting an issue to our GitHub issue tracker. This project provides a bug issue template to help you kickstart your issue.
Even better, you can submit a new Pull Request with a fix.
Please create a new GitHub issue for any major changes and enhancements that you wish to make. Please provide the feature you would like to see, why you need it, and how it will work. Discuss your ideas transparently and get community feedback before proceeding.
Major Changes that you wish to contribute to the project should be discussed first in an GitHub issue that clearly outlines the changes and benefits of the feature.
Small Changes can directly be crafted and submitted to the GitHub Repository as a Pull Request. See the section about Pull Request Submission Guidelines, and for detailed information the core development documentation.
Should you have a suggestion for the documentation, you can open an issue and outline the problem or improvement you have - however, creating the doc fix yourself is much better!
If you want to help improve the docs, it's a good idea to let others know what you're working on to minimize duplication of effort. Create a new issue (or comment on a related existing one) to let others know what you're working on. If you're making a small change (typo, phrasing) don't worry about filing an issue first.
For large fixes, please build and test the documentation before submitting the PR to be sure you haven't accidentally introduced any layout or formatting issues.
TODO: Instructions on building and viewing documentation
This project follows the git flow branching model of development.
The origin/main branch should always reflect a production-ready state, while the origin/development branch is an integration branch reflecting the latest development changes.
A topic branch is a short-lived branch that you create and use for a single particular feature or related work. It is recommended that you create a new topic branch for every new feature you work on.
When you have finished working on a topic branch, you can merge your changes back into the origin/development branch. This is done by creating a pull request. Pull requests are the preferred way to contribute code-changes to this project.
To begin contributing, you will need to fork the main repository to work on your changes. Simply navigate to our GitHub page and click the "Fork" button at the top. Once you've forked the repository, you can clone your new repository and start making edits.
In git, it is best to isolate each topic or feature into a “topic branch”. While individual commits allow you control over how small individual changes are made to the code, branches are a great way to group a set of commits all related to one feature together, or to isolate different efforts when you might be working on multiple topics at the same time.
While it takes some experience to get the right feel about how to break up commits, a topic branch should be limited in scope to a single issue.
To create a new branch and start working on it, run the following commands:
# Checkout the main branch - you want your new branch to come from main
git checkout main
# Create a new branch named newfeature (give your branch its own simple informative name)
git branch newfeature
# Switch to your new branch
git checkout newfeatureFor more information on the GitHub fork and pull-request processes, please see this helpful guide.
Development of this project requires the following tools:
Poetry is a Python package manager that provides a virtual environment for managing dependencies and project configuration. Poetry is required to be installed on your system to develop and build this project.
It's recommended to use at least version 1.5.0 of Poetry to ensure compatibility with this project.
To install Poetry, you can either use the official installation instructions or use the provided script to install Poetry in your home directory:
bash scripts/install-poetry.shTo upgrade Poetry from a previous version, you can run poetry self update to fetch the latest version, or run poetry self update 1.5.0 to update to the project's recommended version.
To setup the poetry environment and install project dependencies, run the below command:
bash scripts/setup-poetry.shThe project contains a top-level ci/ directory containing the CI/CD configuration and environments used in integration, as well as additional configurations for each of the project's development tools when developing locally. Required environments are also automatically configured when using poetry env use <python version> and running the install command in a new virtual environment.
This leverages a root-level pyproject.toml configuration as the source of truth for all of the project's dependencies and development tools. The poetry.lock file is used to lock the project's dependencies to specific versions to ensure that all developers are using the same versions of the project's dependencies. This allows for a consistent development environment across all platforms and Python versions.
Some important caveats and notes about the project's development tools:
-
When configuring a new virtual environment, always use
poetry installto ensure that the project's dependencies are installed and to ensure that the required development tools are installed and configured correctly. This will ensure that the development environment is correctly configured for your virtualenv's Python version. -
When you install the project for the first time, additional required poetry plugins will be installed automatically. These plugins are required for the project's development tools to function correctly, and are automatically added to your poetry configuration with the project's install hook. These plugins are installed globally, and will be available in all of your poetry virtual environments.
-
The project is automatically built by poetry each time you install the project (you can find the built project under
ci/tools/poetry/build). This means that build tools for the CLI or the project's documentation require no pre-requisite setup and only require a single command to build after installation.
The main project is split into two main modules: ocebuild and ocebuild_cli. The ocebuild module contains all of the core functionality of the project, while the ocebuild_cli module contains the CLI interface for the CLI executable.
The third_party module contains all of the third-party code used by the project. This includes vendored code, as well as code that is not available on PyPI. This can include fixes or patches to upstream code, contributed experimental code, or code that is not available on PyPI.
This project uses a custom set of scripts to help manage the development and build process. These scripts are located in the ci/scripts directory. These scripts are intended to be run through the poethepoet plugin, which is installed as part of the setup-poetry.sh script.
To list all available scripts, run poetry run poe. Run a script using poetry <script> or poetry run poe <script>.
Note that scripts listed in the ci/scripts directory must be prefixed with poetry run poe <command>, while scripts listed in the pyproject.toml file can also be run through poetry <command>.
For example, to run the test script, simply run poetry test or poetry run poe test. Only the latter option is available for CI scripts to avoid namespace pollution of Poetry commands.
It's recommended to run the resolve-modules and sort-imports CI scripts before commiting; these scripts will ensure that all module namespaces can properly be resolved and that all imports are sorted correctly. These scripts will run automatically on the pre-commit git hook, but can be run manually by running poetry run poe resolve-modules and poetry run poe sort-imports.
When contributing code to this project, it is important to keep the code style consistent with the rest of the project. This makes it easier for other developers to read the code and understand it. Should the need arise, the project maintainers may ask you to make changes to your code to keep it consistent with the project's style.
For Python code, it's recommended to adhere to the Google Python Style Guide.
Code linting is a type of static analysis that is frequently used to find problematic patterns or code that doesn't adhere to certain style guidelines. By running a linting tool on your code, you can ensure that your code follows the project's style guidelines and that it adheres to the project's quality standards.
For Python code, it's recommended to use pylint to lint your code. Below are some examples of how to lint your code using pylint:
-
Lint unstaged changes to Python files.
git diff --name-only | sed '/.*\.py/!d' | xargs pylint
TODO
TODO
When contributing code to this project, you must agree to license your contribution under the same license that covers the project. In this case, the project is licensed under the BSD 3-Clause License. This license is a permissive open source license that allows for free use of the code for both commercial and non-commercial purposes.
When adding a new file to the project, you must include the license header at the top of the file. This can be done by copying the license header from an existing file in the project and updating the year and author information. Below are some examples of license headers for different programming languages:
This project doesn't enforce any labeling conventions for pull requests, but it's desired to use a short and concise title that addresses the big picture of your changes.
When you are ready to generate a pull request, either for preliminary review, or for consideration of merging into the project you must first push your local topic branch back up to GitHub:
git push origin newfeatureOnce you've committed and pushed all of your changes to GitHub, go to the page for your fork on GitHub, select your development branch, and click the pull request button. If you need to make any adjustments to your pull request, just push the updates to your branch. Your pull request will automatically track the changes on your development branch and update.
- Ensure any install or build dependencies are removed before the end of the layer when doing a build.
- Update the README.md with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters.
- Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is SemVer.
- You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
Except for critical, urgent or very small fixes, we try to leave pull requests open for most of the day or overnight if something comes in late in the day, so that multiple people have the chance to review/comment. Anyone who reviews a pull request should leave a note to let others know that someone has looked at it.
For larger commits, we like to have a +1 from someone else and/or from other contributor(s) before proceeding. Please note if you reviewed the code or tested locally -- a +1 by itself will typically be interpreted as thinking its a good idea, but not having reviewed in detail.
Once a PR has been submitted, your changes will be reviewed and constructive feedback may be provided. Feedback isn't meant as an attack, but to help make sure the highest-quality code makes it into our project. Changes will be approved once required feedback has been addressed.
If a maintainer asks you to "rebase" your PR, they're saying that a lot of code has changed, and that you need to update your fork so it's easier to merge.
To update your forked repository, follow these steps:
# Fetch upstream main and merge with your repo's main branch
git fetch upstream
git checkout main
git merge upstream/main
# If there were any new commits, rebase your development branch
git checkout newfeature
git rebase mainIf too much code has changed for git to automatically apply your branches changes to the new main, you will need to manually resolve the merge conflicts yourself.
Once your new branch has no conflicts and works correctly, you can override your old branch using this command:
git push -fNote that this will overwrite the old branch on the server, so make sure you are happy with your changes first!