Contribute to Nebari's codebase
Thanks for contributing to Nebari's codebase. If you're new to open source software and looking to start your journey, or a seasoned contributor with an issue in mind, we're glad you're here!
Nebari development happens on GitHub and the codebase is hosted at nebari-dev/nebari.
note
Nebari's documentation is hosted on a different repository nebari-dev/nebari-docs
.
To contribute to the documentation, read Contribute to Nebari's documentation.
Select an issue to work onâ
New to Nebari? The issues marked with the "good first issue" label are an excellent place to start. These bug reports and feature requests have a low entry-barrier, need little historical context, and are self-contained. Select a "good first issue" that matches your interest and skill set.
If you feel comfortable contributing the fix/feature directly, write a comment on the issue to let the community know that you are working on it. If you need more context or help with the issue (at any point in your contribution), feel free to ask questions on the same issue. The project maintainers are always happy to support you! Keep in mind that many developers and maintainers are volunteers, so be patient while they get back to your questions. You can drop a reminder after about 4 working days if no one has replied. :)
warning
If you know what you want to work on, and it involves significant API changes, start by creating a new issue or commenting on an existing issue related to it. This allows us to discuss the details and confirm the changes beforehand, and respect the time and energy you spend contributing to Nebari.
Set up your local Nebari repositoryâ
Create a personal copy of the Nebari repository by clicking the
fork
button in the top-right corner.Clone the forked project to your local computer:
git clone https://github.com/<your-username>/nebari.git
Navigate to the project directory:
cd nebari
Add the upstream repository:
git remote add upstream https://github.com/nebari-dev/nebari.git
Now the command git remote -v
shows two remote repositories:
upstream
: which refers to thenebari
repository on GitHub.origin
: which refers to your personal fork.
Set up your development environmentâ
Prerequisitesâ
Operating System: Currently, Nebari supports development on macOS and Linux operating systems. Windows is NOT supported, however we would welcome contributions that add and improve support for Windows.
Python: You need Python >= 3.7 on your local machine, or in your virtual environment to work on Nebari.
Environment managers: You can use tools like
conda
,pipenv
, orvenv
to create an isolated environment for developing Nebari.
Create a virtual environmentâ
The following steps describe how to create and use a conda
environment.
If you don't have
conda
installed, you can follow the installation instructions in theconda
user guide.Create a new environment with:
conda create -n nebari-dev python=3.10
You may need to press Y + Enter/Return to complete the environment build.
Activate the environment with:
conda activate nebari-dev
Install Nebari in "editable" modeâ
With an "editable" installation, all the changes you make to the Nebari codebase will be available in your development environment in real-time. This will also install the required dependencies for development.
You can do this with:
python -m pip install -e .[dev]
note
If you use zsh
, you may need to escape the square brackets:
python -m pip install -e .\[dev\]
note
If you encounter the following issue while attempting to install the development version of Nebari AssertionError: Error getting the version from source vcs
, make sure that all tags were also pulled and synced with your forked git repository (git fetch --tags upstream
), as Nebari heavily depends on those tags as a source to build its development and production versions dynamically.
Pre-commit hooksâ
The nebari
repository uses pre-commit hooks to keep the code format consistent across the codebase.
We encourage regular contributors to install the pre-commit hooks to help with development workflows.
- Before you can run the hooks, you need to install the
pre-commit
package manager:
- conda
- pip
conda install -c conda-forge pre-commit
python -m pip install pre-commit
- Install the pre-commit hooks:
pre-commit install
- (Optional) Run the hooks against the files in this repository:
pre-commit run --all-files
Once installed, the pre-commit hooks will run automatically when you make a commit in version control.
Develop your contributionâ
Before you start, make sure to pull the latest changes from upstream.
git checkout develop
git pull upstream developCreate a branch for the bug or feature you want to work on. The branch name will appear in the merge message, so use a sensible, self-explanatory name:
git branch feature/<feature name>
git switch feature/<feature name>
# this is an alternative to the git checkout -b feature/<feature name> commandCommit locally as you progress (
git add
andgit commit
), and make sure to use an adequately formatted commit message.
Testingâ
Tests are an important part of development. In your contributions, always include tests that fail before your change and pass afterwards. Run all the tests locally and make sure that they pass before submitting your contribution. If you need help with a test case, you can create a draft pull request and message the maintainers for help.
For tips and best practices, read Test your Nebari contribution ->
Document changesâ
Prioritize including relevant documentation with your contributions to help your code reviewers, Nebari users, as well as other contributors who may interact with your code.
- Add comments to explain intricacies in your code and share "why" it is needed. If you reference a particular GitHub issue or PR, use
gh-xxxx
(wherexxxx
indicated the issue/PR number.) - If your contribution changes the behavior of a function, be sure to document it in the function's docstring. As a reminder, we follow the Google Style Guide for docstrings formatting.
- Update any relevant pages on narrative documentation on
nebari.dev
. Read Contribute to Nebari's documentation for more details. - If your change introduces any user-facing modifications, mention in the release notes.
Submitting your contributionâ
When you feel comfortable with your contribution, you can open a pull request (PR) to submit it for review!
You can also submit partial work to get early feedback on your contribution or discuss some implementation details.
If you do so, add WIP
(work in progress) in the PR title and mark it as a draft.
Push your changes back to your fork on GitHub:
git push origin feature/<feature name>
Enter your GitHub username and password (repeat contributors or advanced users can remove this step by connecting to GitHub with SSH).
Go to the Nebari repository on GitHub. You will see a green pull request button. Make sure the title and message are clear, concise, and self-explanatory. Complete the checklist and read the notes in the PR template, then click the button to submit it.
note
If the PR relates to any issues, you can add the text xref gh-xxxx
where xxxx
is the issue number to GitHub comments.
Likewise, if the PR solves an issue, replace the xref
with closes
, fixes
or any other flavors GitHub accepts.
GitHub will automatically close the corresponding issue(s) when your PR gets merged.
Review processâ
Reviewers (the other developers and interested community members) will write inline and general comments on your pull request (PR) to help you improve its implementation, documentation, and style. Every developer working on the project has their code reviewed, and we've come to see it as a friendly conversation from which we all learn and the overall code quality benefits. Therefore, please don't let the review discourage you from contributing: its only aim is to improve the quality of the project, not to criticize (we are, after all, very grateful for the time you're donating!).
To update your PR to incorporate the suggestions, make your changes on your local repository, commit them, run tests, and only if they succeed, push to your fork. The PR will update automatically as soon as those changes are pushed up (to the same branch as before).
Continuous Integrationâ
Various continuous integration (CI) pipelines are triggered after each PR update to build artifacts, run unit tests, and check the coding style of your branch. To avoid overuse of this resource, test your work locally before committing. We require the CI tests to pass before your PR can be merged. If CI fails, you can find why by clicking on the "failed" icon (red cross) and inspecting the build and test log. If you need help to fix the test failures, you may push your changes anyway and ask for help in a PR comment.
note
We also require a PR to be approved by at least one core team member. Approval means the core team member has carefully reviewed the changes, and the PR is ready for merging.