Contributor workflow#

openplaces is public on Github.

Understanding the contributor workflow helps you make clean and well-tested contributions.

We assume you have installed openplaces: you have a local clone of the repository and a conda environment on your machine. Otherwise, do that first.

We also assume prior knowledge of git.

Best practices#

We adopt the Git version control best practices from Gitlab:

Develop using branches#

We use the feature branching strategy: one branch per feature.

If you wish to make a contribution to openplaces, follow these steps:

Create your own branch:
```
git pull origin main
git switch -c create-new-feature  # pick a name
```
Pick a short name that identifies the feature to collaborators.
Edit your code.
Test your code.
Format your code.
Commit your changes to your branch:
```
git add <filename>
git commit -m "Create new feature"
```
This will trigger automatic code style checks.
Push your changes to create a pull request.

Before you push, pull recent changes to the repository. This ensures your commits reflect the most recent version of the repository.
```
git pull --rebase origin main
```
The first time you push, you have to register the branch upstream:
```
git push -u origin create-new-feature
```
The next time you push, the branch is already registered:
```
git push
```
If your contributions pass review, they become part of the main branch. Your Github badge will appear on the public list of collaborators.

Activate your environment#

Make sure your openplaces environment is active before using git:

conda activate openplaces

This is important because git needs:

nbstripout to strip notebook outputs
pre-commit and ruff for enforcing code style checks.

Format your code#

Clean code makes contributions more readable and interpretable.

openplaces adopts ruff to format and lint Python code in both scripts and notebooks before committing them to the repository (any branch).

We adopt ruff’s default specifications and add two more:

Use single quotes for strings ('hello', not "hello").

It looks cleaner and is faster to type on many keyboards.
Identify openplaces as a “known first party” to isort.

This ensures that imports from openplaces appear in a separate (third) section after standard Python libraries (1st) and external packages (2nd).

To edit these and other settings, find and edit these two files:

notebooks/ruff.toml to format Jupyter notebook cells with jupyter-ruff, see next section.
pyproject.toml for command-line ruff and pre-commit hooks.

Jupyter notebooks#

jupyter-ruff makes ruff formatting available in Jupyter notebooks:

Right-click to the left of the cell
Select Format Cell using Ruff.

You can choose to automatically format notebooks when saving:

Select Settings from the menu of your Jupyter homepage (directory view). You can access it from any notebook by clicking the Jupyter icon on the top left.
Click Settings Editor.
Find Jupyter Ruff in the left-hand menu.
Check the checkbox Format on Save.

Note

Turning on Format On Save can trigger unwanted error popups if automated saving occurs while you are editing a cell and ruff fails to format the incomplete code.

Python scripts#

Before you git add any changes to Python scripts and Jupyter notebooks, make sure your code is compliant with the style format.

Do do so, run ruff check or ruff format in your Terminal:

# Check a file
ruff check yourfolder/yourfilename.ext

# Check a folder
ruff check yourfolder

# Format a file (fixes many issues)
ruff format yourfolder/yourfilename.ext

Once the code passes these checks, it will also pass the pre-commit hooks.

Strip outputs from notebooks#

openplaces uses nbstripout to remove outputs from Jupyter notebooks (e.g., figures, prints, warnings, errors) before adding them to the repository.

This will occur automatically: it is set in .gitattributes in the repository root. You just need to make sure your openplaces environment is active.

Note

User switching between machines or operating systems can lose their connection to nbstripout. If you encounter errors related to nbstripout while your openplaces environment is active, re-running nbstripout --install frequently resolves the issue.

Pass the pre-commit hooks#

openplaces uses pre-commit hooks to make sure your code is compliant with the ruff code style before it becomes part of the repository.

These hooks are triggered when you try to commit changes to the repository:

git add filenames.here
git commit -m "Your commit message here."

pre-commit will install a temporary environment and test your code against ruff code style.

ruff will implement non-risky fixes. It will also tell you about any issues that weren’t fixed and that you have to edit manually.

If fixes were implemented (automatically or by you), you need to re-add the edited files and re-commit them, until you pass all checks.