Skip to content

Latest commit

 

History

History
165 lines (102 loc) · 5.65 KB

CONTRIBUTING.md

File metadata and controls

165 lines (102 loc) · 5.65 KB

So You Want to Contribute to Papermill!

We welcome all contributions to Papermill, both large and small. We encourage you to join our community.

Our Community Values

We are an open and friendly community. Everybody is welcome.

We encourage friendly discussions and respect for all. There are no exceptions.

All contributions are equally important. Documentation, answering questions, and fixing bugs are equally as valuable as adding new features.

Please read our entire Code of Conduct.

Setting up Your Development Environment

Following these instructions should give you an efficient path to opening your first pull request.

Cloning the Papermill Repository

Fork the repository to your local GitHub account. Clone this repository to your local development machine.

git clone https://github.com/<your_account>/papermill
cd papermill

Install an Editable Version

We prefer to use a native virtual environment (venv) to manage the development environment.

python3 -m venv dev
source dev/bin/activate

Install Papermill using:

pip install -e '.[dev]'

or use conda if you prefer conda:

conda create -n dev
. activate dev

Note: When you are finished, you can use source deactivate to go back to your base environment.

Running Tests Locally

If you are contributing to documentation, please jump to building documentation.

We need to install the development package before running the tests. If anything is unclear below, please refer to the relevant documentation.

For the most basic test runs against Python 3.12, use this tox subset (callable after pip install tox):

tox -e py312

This will execute the unittests against Python 3.12 in a new virtual environment. The first run will take longer to set up the virtualenv, but will be fast after that point.

To run the full test suite for all environments and linting checks, use the 'tox' command without any arguments.

tox

This will require Python 3.10, 3.11, 3.12, and 3.13 to be installed.

Alternatively, pytest can be used if you have an environment already set up that works or has custom packages not present in the tox build.

pytest

Now there should be a working and editable installation of Papermill to start making your own contributions.

Building Documentation

The documentation is built using the Sphinx engine. To contribute, edit the RestructuredText (.rst) files in the docs directory to make changes and additions.

Once you are done editing, to generate the documentation, use tox and the following command from the root directory of the repository:

tox -e docs

This will generate .html files in the /.tox/docs_out/ directory. Once you are satisfied, you can just jump to the next section.

So You're Ready to Pull Request

The general workflow for this will be:

  1. Run local tests
  2. Pushed changes to your forked repository
  3. Open pull request to main repository

Run Tests Locally

pytest --pyargs papermill

Run check manifest to ensure all files are accounted for in the repository.

check-manifest

This command read the MANIFEST.in file and explicitly specify the files to include in the source distribution. You can read more about how this works here.

Push Changes to Forked Repo

Your commits should be pushed to the forked repository. To verify this type

git remote -v

and ensure the remotes point to your GitHub. Don't work on the main branch!

  1. Commit changes to local repository:

    git checkout -b my-feature
git add <updated_files>
git commit

  2. Push changes to your remote repository:

    git push -u origin my-feature

Create Pull Request

Follow these instructions to create a pull request from a forked repository. If you are submitting a bug fix for a specific issue, ensure that you reference the issue in the pull request.

There are good references to the Git documentation and Git workflows for more information if any of this is unfamiliar.

Note: You might want to set a reference to the main repository to fetch/merge from there instead of your forked repository. You can do that using:

git remote add upstream https://github.com/nteract/papermill

It's possible you will have conflicts between your repository and main. Here, main is meant to be synchronized with the upstream repository. GitHub has some good documentation on merging pull requests from the command line.

Use of Generative AI Tools

Generative AI tools have evolved rapidly, and their suggested results can be helpful. As with using any tool, the resulting contribution is the responsibility of the contributor. We value good code, concise and accurate documentation, and avoiding unnecessary code churn. Discretion, good judgment, and critical thinking are the foundation of all good contributions, regardless of the tools used in their creation.

Adapted from the Python developer guide.

🚀 Happy hacking on Papermill! 💐