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.
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
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
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.
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 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 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