Contributing

Setup

To work on Fixit, you’ll need to use Hatch. We recommend installing it via pipx, but any of these alternatives will work.

Fixit requires at least Python 3.8. If you do not have an appropriate version, or if you would like to test with newer runtimes, you can use pyenv to build and manage versions.

Developing

Fixit can be built and run locally using hatch:

$ hatch env run -- fixit [args]

You can also use the managed virtualenv:

$ hatch shell

$ fixit [args]

To run the test suite, type checker, and linters individually:

$ hatch run test

$ hatch run typecheck

$ hatch run lint:check

To format code, sort imports, and apply automatic lint fixes:

$ hatch run lint:fix

Documentation is built using sphinx. You can generate and view the documentation locally in your browser:

$ hatch run docs:build

$ open html/index.html

To run the full test, typecheck, lint suite, and build the docs all at once, you can use make:

$ make

Submitting PRs

Before submitting PRs, please address the following items:

  • Add tests exercising any fixed bugs or new functionality

  • Document any changes to configuration or behavior

  • Apply formatting, regenerate documentation, and run the test suite (see above)

  • Summarize the high level features or behavior changes in your commit message

For most developers, we recommend using the github cli to submit pull requests:

$ gh pr create

If you are a Fixit maintainer, we recommend using ghstack (see below):

$ ghstack submit

Code style

You can ensure your changes are well formatted, and imports are sorted:

$ hatch run lint:fix

If you are using VS Code as your editor, you can use the µfmt plugin for VSCode to easily enable formatting and import sorting while developing.

VS Code

To help VS Code find your hatch environments, and all of Fixit’s dependencies, you can symlink the appropriate hatch environments into your local checkout:

$ hatch env create
...

$ ln -s $(hatch env find) .venv

Now, the VS Code Python module should be able to find and offer the local .venv path as an option for your active Python environment, and should then be aware of what libraries are available, and enable “Go To Definition” for those packages.

git-branchless

git-branchless is a useful tool for improving your local git CLI workflow, especially within a stack of commits. It provides a “smartlog” command (git sl) to help visual the hierarchy of commits and branches in your checkout, as well as next/prev commands to make moving through your stacks even easier:

amethyst@luxray ~/workspace/Fixit docs  » git sl
⋮
◇ a80603c 226d (0.x) Update 'master' (branch) references to 'main' (#220)
⋮
◆ c3f8ff9 52d (main, ᐅ docs) Include scripts dir in linters
┃
◯ 33863f4 52d (local-rules) Simple example of local rule for copyright headers

git-branchless is a Rust package, and can be installed with cargo:

$ cargo install --locked git-branchless

Once installed to your system, it must be enabled on each git repo that you want to use it with, so that it can install hooks and new commands:

$ git branchless init

ghstack

ghstack is a tool for simplifying and automating the process of submitting stacked PRs, where each PR in the stack builds and depends on changes from the previous PR.

Unfortunately, ghstack requires push access to the upstream repo, so this can only be used by project maintainers.

ghstack is a Python package, and we recommend installing it using pipx:

$ pipx install ghstack

Once installed, you can run ghstack to submit a stack of PRs from your active branch, one PR for each commit in the branch:

$ ghstack submit

Note that any PRs created with ghstack cannot be merged using the normal Github merge UI — you must use ghstack to “land” the stack so that it can automatically rebase and merge each commit in the correct order, and update any outstanding PRs accordingly. You can do this by passing the URL to the last PR in the stack that you want to land:

$ ghstack land $PR_URL