Skip to content

Latest commit

 

History

History
296 lines (194 loc) · 8.7 KB

CONTRIBUTING.md

File metadata and controls

296 lines (194 loc) · 8.7 KB

Contributing

Getting Help

Please use our github and raise an issue at: https://github.com/automl/extrapolaw

Development Workflow

We use one main branch master and feature branches for development. We use pull requests to merge feature branches into master. Versions released to PyPI are tagged with a version number.

Automatic checks are run on every pull request and on every commit to master.

Installation

There are four steps:

  1. Install uv
  2. Clone the extrapolaw repository
  3. Create virtual env and install the extrapolaw package
  4. Activate pre-commit for the repository

For instructions see below.

1. Install uv

First, install uv, e.g., via

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the extrapolaw repository

git clone https://github.com/automl/extrapolaw.git
cd extrapolaw

3. Create a virtual environment and install the extrapolaw package

uv venv --python 3.11
source .venv/bin/activate

Then, inside the main directory of extrapolaw run

uv pip install -e ".[dev]"

This will installthe extrapolaw package but also additional dev dependencies.

4. Activate pre-commit for the repository

With the python environment used to install the extrapolaw package run in the main directory of extrapolaw

pre-commit install

This install a set of hooks that will run basic linting and type checking before every comment. If you ever need to unsinstall the hooks, you can do so with pre-commit uninstall. These mostly consist of ruff for formatting and linting and mypy for type checking.

We highly recommend you install at least ruff either on command line, or in the editor of your choice, e.g. VSCode, PyCharm.

We have setup checks and tests at several points in the development flow:

  • At every commit we automatically run a suite of pre-commit hooks that perform static code analysis, autoformating, and sanity checks. This is setup during our installation process.
  • At every commit / push locally running a minimal suite of integration tests is encouraged. The tests correspond directly to examples in extrapolaw_examples and only check for crash-causing errors.

Checks and tests

Linting (Ruff)

For linting we use ruff for checking code quality. You can install it locally and use it as so:

uv pip install ruff
ruff check --fix extrapolaw  # the --fix flag will try to fix issues it can automatically

This will also be run using pre-commit hooks.

To ignore a rule for a specific line, you can add a comment with ruff: disable at the end of the line, e.g.

for x, y in zip(a, b):  # noqa: <ERRCODE>
    pass

The configuration of ruff is in the pyproject.toml file and we refer you to the documentation if you require any changes to be made.

There you can find the documentation for all of the rules employed.

Type Checking (Mypy)

For type checking we use mypy. You can install it locally and use it as so:

uv pip install mypy
mypy extrapolaw

Types are helpful for making your code more understandable by your editor and tools, allowing them to warn you of potential issues, as well as allow for safer refactoring. Copilot also works better with types.

To ignore some error you can use # type: ignore at the end of the line, e.g.

code = "foo"  # type: ignore

A common place to ignore types is when dealing with numpy arrays, tensors and pandas, where the type checker can not be sure of the return type.

df.mean()  # Is this another dataframe, a series or a single number?

In the worse case, please just use Any and move on with your life, the type checker is meant to help you catch bugs, not hinder you. However it will take some experience to know whe it's trying to tell you something useful vs. something it just can not infer properly. A good rule of thumb is that you're only dealing with simple native types from python or types defined from Extrapolaw, there is probably a good reason for a mypy error.

If you have issues regarding typing, please feel free to reach out for help @eddiebergman.

Mypy: How to ignore warnings?

There are two options:

  • Disable the warning locally:

    code = "foo"  # type: ignore

Examples and Integration Tests

We use some examples in extrapolaw_examples as integration tests, which we run from the main directory via

pytest

If tests fail for you on the master, please raise an issue on github, preferably with some information on the error, traceback and the environment in which you are running, i.e. python version, OS, etc.

Pre-commit: How to not run hooks?

To commit without running pre-commit use git commit --no-verify -m <COMMIT MESSAGE>.

Managing Dependencies

To manage dependencies we use uv (replaces pip).

Add dependencies

To install a dependency use

uv add dependency

and commit the updated pyproject.toml to git.

For more advanced dependency management see examples in pyproject.toml or have a look at the uv documentation.

Install dependencies added by others

When other contributors added dependencies to pyproject.toml, you can install them via

uv pip install -e ".[dev]"

Documentation

We use MkDocs, more specifically Material for MkDocs for documentation. To support documentation for multiple versions, we use the plugin mike.

Source files for the documentation are under /docs and configuration at mkdocs.yml.

To build and view the documentation run

mike deploy 0.5.1 latest
mike serve

and open the URL shown by the mike serve command.

To publish the documentation run

mike deploy 0.5.1 latest -p

Releasing a New Version

There are five steps to releasing a new version of extrapolaw:

  1. Understand Semantic Versioning
  2. Run Tests
  3. Bump the Version on a Release Branch
  4. Merge and Tag on Master
  5. Update Documentation
  6. Publish on PyPI

0. Understand Semantic Versioning

We follow the semantic versioning scheme.

1. Run Tests

uv run pytest

2. Bump the Version on a Release Branch

The version is bumped on a release branch and merged through a PR:

git checkout master && git pull
git checkout -b release/v<new_version>
bump-my-version bump <major | minor | patch>
git push -u origin release/v<new_version>

This creates one release commit with the following changes. Preview them first with --dry-run -vv and check:

  • CHANGELOG.md: the current ## [Unreleased] entries become ## [<new_version>] - <today>, and a new empty ## [Unreleased] heading is added above them. Make sure the Unreleased section is complete before bumping.
  • CITATION.cff: version is bumped. date-released is not updated automatically, so set and commit it before bumping (the bump needs a clean working tree).
  • pyproject.toml: version and current_version in [tool.bumpversion] are bumped.

No tag is created at this step (tag = false): PRs are squash-merged, which gives the commit a new ID, so a tag made on the release branch would not point to a commit on master.

3. Merge and Tag on Master

Open a PR from the release branch and merge it. Then tag the merged commit on master:

git checkout master && git pull
git tag v<new_version>
git push origin v<new_version>

4. Update Documentation

First check if the documentation has any issues via

mike deploy <current version> latest -u
mike serve

and then looking at it.

Update the citation.cff page and citations.md page in the docs directory and in pyproject.toml.

Afterwards, publish it via

mike deploy <current version> latest -up

5. Publish on PyPI

To publish to PyPI:

  1. Get publishing rights, e.g., asking Danny or Neeratyoy.
  2. Be careful, once on PyPI we can not change things.
  3. Run
uv build
uv publish

This will ask for your PyPI credentials.