Contributing Guide

Note

Parts of this document are based on Contributing to pandas and Contributing to xarray.

We welcome your enthusiasm! All contributions, including bug reports, bug fixes, documentation improvements, enhancement suggestions, and other ideas are welcome.

If you have any questions, feel free to ask us! The recommended place to ask questions is GitHub Discussions.

Bug reports and enhancement requests

If you find a bug in the code or documentation, do not hesitate to submit a ticket to the Issue Tracker. You are also welcome to post feature requests or pull requests.

When reporting a bug, see this stackoverflow article for tips on writing a good bug report, and this article on minimal bug reports.

Creating a development environment

First, you will need to install git and conda (or mamba).

Installing git

Below are some quick instructions for installing git on various operating systems. For more detailed instructions, see the git installation guide.

  • macOS (Intel & ARM): get Xcode Command Line Tools by running in your terminal window:

    xcode-select --install

  • Windows 10 1709 (build 16299) or later: run in command prompt or PowerShell:

    winget install --id Git.Git -e --source winget

If you are new to contributing to projects through forking on GitHub, take a look at the GitHub documentation for contributing to projects. GitHub provides a quick tutorial using a test repository that may help you become more familiar with forking a repository, cloning a fork, creating a feature branch, pushing changes and making pull requests.

Below are some useful resources for learning more about forking and pull requests on GitHub:

Cloning the repository

  1. Create an account on GitHub if you do not already have one.

  2. You will need your own copy of erlabpy (aka fork) to work on the code. Go to the erlabpy repository and hit the Fork button near the top of the page. This creates a copy of the code under your account on the GitHub server.

  3. Clone your fork to your machine:

    git clone https://github.com/your-user-name/erlabpy.git
cd erlabpy
git remote add upstream https://github.com/kmnhan/erlabpy.git

    This creates the directory erlabpy and connects your repository to the upstream (main project) erlabpy repository.

Installing conda

Before starting any development, you’ll need to create an isolated environment under a package manager like conda. If you don’t have conda installed, install conda or install mamba.

Hint

  • When using conda, miniconda is recommended to save disk space.

  • Mamba is a faster alternative to conda with additional features.

  • Installing miniforge will install both conda and mamba, and is recommended.

Editable installation from source

An editable installation allows you to make changes to the code and see the changes reflected in the package without having to reinstall it. Before installing:

  1. Create and activate a mamba (or conda) environment.

    Note

    Replace <envname> with the environment name you prefer.

    Hint

    If using conda, replace mamba with conda.

    mamba env create -f environment.yml -n <envname>
mamba activate <envname>

  2. Install the repository.

    Note

    The editable_mode=compat setting enables static analysis tools to work with the package. See this issue for more information.

    pip install -e ".[dev]" --config-settings editable_mode=compat

Updating the editable installation

  • For minor updates with editable installs, it is sufficient to just update the main branch.

  • When there are changes to the dependencies, you should also update the environment:

    Hint

    If using conda, replace mamba with conda.

    mamba env update -f environment.yml -n <envname>

  • In case of major changes, it is recommended to rebuild the package.

    mamba activate <envname>
pip install -e . --force-reinstall --no-deps --config-settings editable_mode=compat

Development workflow

Before starting any development, make sure you have created a local development environment.

Update the main branch

Before starting a new set of changes, fetch all changes from upstream/main, and start a new feature branch from that. From time to time you should fetch the upstream changes from GitHub:

git fetch upstream
git merge upstream/main

This will combine your commits with the latest erlabpy git main. If this leads to merge conflicts, you must resolve these before submitting your pull request. Remember to follow the commit message guidelines. If you have uncommitted changes, you will need to git stash them prior to updating. This will effectively store your changes, which can be reapplied after updating with git stash apply.

Create a new feature branch

Create a branch to save your changes, even before you start making changes. You want your main branch to contain only production-ready code:

git checkout -b shiny-new-feature

This changes your working directory to the shiny-new-feature branch. Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to erlabpy. You can have many “shiny-new-features” and switch in between them using the git checkout command.

Generally, you will want to keep your feature branches on your public GitHub fork of erlabpy. To do this, you git push this new branch up to your GitHub repo. Generally (if you followed the instructions in these pages, and by default), git will have a link to your fork of the GitHub repo, called origin. You push up to your own fork with:

git push origin shiny-new-feature

In git >= 1.7 you can ensure that the link is correctly set by using the --set-upstream option:

git push --set-upstream origin shiny-new-feature

From now on git will know that shiny-new-feature is related to the shiny-new-feature branch in the GitHub repo.

The editing workflow

  1. Make some changes. Make sure to follow the code standards and the documentation standards.

  2. See which files have changed with git status. You’ll see a listing like this one:

    # On branch shiny-new-feature
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#  modified:   README

  3. Check what the actual changes are with git diff.

  4. Build the documentation for documentation changes. See the documentation section for more information.

Commit and push your changes

  1. To commit all modified files into the local copy of your repo, do git commit -am 'A commit message'. Note that erlabpy uses python-semantic-release for versioning, so the commit message must follow the Conventional Commits standard. This will automatically determine the version number for the next release.

  2. To push the changes up to your forked repo on GitHub, do a git push.

Open a pull request

When you’re ready or need feedback on your code, open a Pull Request (PR) so that we can give feedback and eventually include your suggested code into the main branch. Pull requests (PRs) on GitHub are the mechanism for contributing to the code and documentation.

Enter a title for the set of changes with some explanation of what you’ve done. Mention anything you’d like particular attention for - such as a complicated change or some code you are not happy with. If you don’t think your request is ready to be merged, just say so in your pull request message and use the “Draft PR” feature of GitHub. This is a good way of getting some preliminary code review.

Code standards

  • Import sorting, formatting, and linting are enforced with Ruff.

  • If you wish to contribute, using pre-commit is recommended. This will ensure that your code is properly formatted before you commit it. A pre-commit configuration file for ruff is included in the repository.

  • When writing code that uses Qt, please adhere to the following rules:

    • Import all Qt bindings from qtpy, and only import the top level modules:

      from qtpy import QtWidgets, QtCore, QtGui

    • Use fully qualified enum names from Qt6 instead of the short-form enums from Qt5, i. e., QtCore.Qt.CheckState.Checked instead of QtCore.Qt.Checked.

    • Use the signal and slot syntax from PySide6 (QtCore.Signal and QtCore.Slot instead of QtCore.pyqtSignal and QtCore.pyqtSlot)

    • When using Qt Designer, place .ui files in the same directory as the Python file that uses them. The files must be imported using the loadUiType function from qtpy.uic. For example:

      from qtpy import uic

class MyWidget(*uic.loadUiType(os.path.join(os.path.dirname(__file__), "mywidget.ui"))):
    def __init__(self):
        super().__init__()
        self.setupUi(self)

  • Please try to add type annotations to your code. This will help with code completion and static analysis.

  • We are in the process of adding type annotations to the codebase, and most of it should pass mypy except for the io and interactive modules.

Documentation

The documentation is written in reStructuredText, which is almost like writing in plain English, and built using Sphinx. The Sphinx Documentation has an excellent introduction to reST. Review the Sphinx docs to perform more complex changes to the documentation as well.

Some other important things to know about the docs:

  • The documentation consists of two parts: the docstrings in the code itself and the docs in this folder erlabpy/docs/source/.

    The docstrings are meant to provide a clear explanation of the usage of the individual functions, while the documentation in this folder consists of tutorial-like overviews per topic together with some other information.

  • The docstrings follow the NumPy Docstring Standard, which is used widely in the Scientific Python community. This standard specifies the format of the different sections of the docstring. Refer to the documentation for the Numpy docstring format and the Sphinx examples for detailed explanation and examples, or look at some of the existing functions to extend it in a similar manner.

  • The documentation is automatically updated by Read the Docs when a new commit is pushed to main.

  • Type annotations that follow PEP 484 are recommended in the code, which are automatically included in the documentation. Hence, you may omit the type information for well-annotated functions.

  • We aim to follow the recommendations from the Python documentation and the Sphinx reStructuredText documentation for section markup characters,

    • * with overline, for chapters

    • =, for heading

    • -, for sections

    • ~, for subsections

    • ** text **, for bold text

Building the documentation locally

Check whether all documentation dependencies are installed with

pip install -r docs/requirements.txt

or

mamba env update -f docs/environment.yml -n <envname>

then build the documentation by running:

cd docs/
make clean
make html

Then you can find the HTML output files in the folder erlabpy/docs/build/html/.

To see what the documentation now looks like with your changes, you can view the HTML build locally by opening the files in your local browser. For example, if you normally use Google Chrome as your browser, you could enter:

google-chrome build/html/index.html

in the terminal, running from within the doc/ folder. You should now see a new tab pop open in your local browser showing the documentation. The different pages of this local build of the documentation are linked together, so you can browse the whole documentation by following links the same way you would on the hosted website.