Contributing

We welcome contributions to Import Linter.

Bug reports

When reporting a bug please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Feature requests and feedback

The best way to send feedback is to file an issue at https://github.com/seddonym/import-linter/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible.
Remember that this is a volunteer-driven project.

Submitting pull requests

Before spending time working on a pull request, we highly recommend filing a Github issue and engaging with the project maintainer (David Seddon) to align on the direction you're planning to take. This can save a lot of your precious time!

This doesn't apply to trivial pull requests such as spelling corrections.

For merging, you should:

Include passing tests (run just test-all).
Update documentation when there's new API, functionality etc.
Add a note to docs/release_notes.md about the changes.
Add yourself to docs/authors.md (in alphabetical order).

Development

System prerequisites

Make sure these are installed first.

Setup

You don't need to activate or manage a virtual environment - this is taken care in the background of by uv.

Fork import-linter (look for the "Fork" button).

Clone your fork locally:

git clone git@github.com:your_name_here/import-linter.git

Change into the directory you just cloned:
```
cd import-linter
```
Set up pre-commit. (Optional, but recommended.):
```
just install-precommit
```

You will now be able to run commands prefixed with just, providing you're in the Import Linter directory. To see available commands, run just.

Formatting code

just format

Running linters

just lint

Running tests

When you're developing a feature, you'll probably want to run tests quickly, using just the latest supported Python version:

just test

You can also pass a specific Python version, e.g. just test --python=3.13.

If you want to invoke pytest directly, e.g. to run a specific test, just use uv run pytest, e.g.:

uv run pytest tests/unit/contracts

Finally, you can run all the tests under all supported Python versions with just test-all. This gives a more complete picture of whether the changes are compatible with all supported versions. Additionally, it will run tests under the lowest versions of dependencies specified in pyproject.toml, with the lowest supported Python version.

Before you push

It's a good idea to run just check before getting a review. This will run linters, docs build and tests under every supported Python version.

Building documentation

To view docs locally:

just serve-docs

Or, if you just want to build them:

just build-docs

Releasing to Pypi

(Only maintainers can do this.)

Choose a new version number (based on semver).
git pull origin main
Update docs/release_notes.md with the new version number.
Update the __version__ variable in src/importlinter/__init__.py with the new version number.
Update project.version in pyproject.toml with the new version number.
git commit -am "Release v{new version number"
git push
Wait for tests to pass on CI.
git tag v{new version number}
git push --tags
This should kick start the Github release workflow which releases the project to PyPI.