diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 704a41b1a..0d5211e4a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -11,6 +11,7 @@ Merge checklist: - [ ] Pull Request title is [short, imperative summary](https://cbea.ms/git-commit/) of proposed changes - [ ] The description documents the _what_ and _why_ +- [ ] This PR has been [linted](https://docs.photonvision.org/en/latest/docs/contributing/linting.html). - [ ] If this PR changes behavior or adds a feature, user documentation is updated - [ ] If this PR touches photon-serde, all messages have been regenerated and hashes have not changed unexpectedly - [ ] If this PR touches configuration, this is backwards compatible with settings back to v2025.3.2 diff --git a/docs/source/docs/contributing/index.md b/docs/source/docs/contributing/index.md index 4de6c437a..80b8487ef 100644 --- a/docs/source/docs/contributing/index.md +++ b/docs/source/docs/contributing/index.md @@ -3,6 +3,7 @@ ```{toctree} building-photon building-docs +linting developer-docs/index design-descriptions/index ``` diff --git a/docs/source/docs/contributing/linting.md b/docs/source/docs/contributing/linting.md new file mode 100644 index 000000000..690113c68 --- /dev/null +++ b/docs/source/docs/contributing/linting.md @@ -0,0 +1,43 @@ +# Linting the PhotonVision Codebase + +## Versions + +:::{note} +If you work on other projects that use different versions of the same linters as PhotonVision, you may find it beneficial to use a [venv](https://docs.python.org/3/library/venv.html) instead of installing the linters globally. This will allow you to have different versions of the same linter installed for different projects. +::: + +The correct versions for each linter can be found under the linting workflow located [here](https://github.com/PhotonVision/photonvision/tree/main/.github/workflows). For *doc8*, the version can be found in `docs/requirements.txt`. If you've linted, and are still unable to pass CI, please check the versions of your linters. + +## Frontend + +### Linting the frontend + +In order to lint the frontend, run `pnpm -C photon-client lint && pnpm -C photon-client format`. This should be done from the base level of the repo. + +## Backend + +### wpiformat installation + +To lint the backend, PhotonVision uses *wpiformat* and *spotless*. Spotless is included with gradle, which means installation is not needed. To install wpiformat, run `pipx install wpiformat`. To install a specific version, run `pipx install wpiformat==`. + +### Linting the backend + +To lint, run `./gradlew spotlessApply` and `wpiformat`. + +## Documentation + +### doc8 installation + +To install *doc8*, the python tool we use to lint our documentation, run `pipx install doc8`. To install a specific version, run `pipx install doc8==`. + +### Linting the documentation + +To lint the documentation, run `doc8 docs` from the root level of the docs. + +## Alias + +The following [alias](https://www.computerworld.com/article/1373210/how-to-use-aliases-in-linux-shell-commands.html) can be added to your shell config, which will allow you to lint the entirety of the PhotonVision project by running `pvLint`. The alias will work on Linux, macOS, Git Bash on Windows, and WSL. + +```sh +alias pvLint='wpiformat -v && ./gradlew spotlessApply && pnpm -C photon-client lint && pnpm -C photon-client format && doc8 docs' +```