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. :)

Caution

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

1. Create a personal copy of the Nebari repository by clicking the fork button in the top-right corner.

2. Clone the forked project to your local computer:

   git clone https://github.com/<your-username>/nebari.git

3. Navigate to the project directory:

   cd nebari

4. 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 the nebari repository on GitHub.
• origin: which refers to your personal fork.

Set up your development environment

Prerequisites

1. 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.

2. Python: You need Python >= 3.7 on your local machine, or in your virtual environment to work on Nebari.

3. Environment managers: You can use tools like conda, pipenv, or venv to create an isolated environment for developing Nebari.

Create a virtual environment

The following steps describe how to create and use a conda environment.

1. If you don't have conda installed, you can follow the installation instructions in the conda user guide.

2. 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.

3. 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.

1. Before you can run the hooks, you need to install the pre-commit package manager:

conda

conda install -c conda-forge pre-commit

pip

python -m pip install pre-commit

2. Install the pre-commit hooks:

pre-commit install

3. (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

1. Before you start, make sure to pull the latest changes from upstream.

   git checkout develop
   git pull upstream develop

2. Create 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> command

3. Commit locally as you progress (git add and git 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 (where xxxx 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.

1. Push your changes back to your fork on GitHub:

   git push origin feature/<feature name>

2. Enter your GitHub username and password (repeat contributors or advanced users can remove this step by connecting to GitHub with SSH).

3. 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.

Additional resources

• GitHub documentation on Contributing to projects