From 374ab53086970bc043593f5c9021ad2b96ff0754 Mon Sep 17 00:00:00 2001 From: samfreund Date: Thu, 30 Oct 2025 11:46:40 -0500 Subject: [PATCH 1/7] add documentation for linting --- docs/source/docs/contributing/index.md | 1 + docs/source/docs/contributing/linting.md | 39 ++++++++++++++++++++++++ 2 files changed, 40 insertions(+) create mode 100644 docs/source/docs/contributing/linting.md diff --git a/docs/source/docs/contributing/index.md b/docs/source/docs/contributing/index.md index 4de6c437af..80b8487ef2 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 0000000000..baa5ba162c --- /dev/null +++ b/docs/source/docs/contributing/linting.md @@ -0,0 +1,39 @@ +# Linting the PhotonVision Codebase + +## Frontend + +### Installation + +In order to lint the frontend, it's necessary to install `prettier`. This can be done by running `npm install prettier --global`. + +### Linting + +In order to lint the frontend, run `prettier --write photon-client/* --ignore-path photon-client/.prettierignore`. This should be done from the base level of the repo. The command above is meant for linux, if you're using Windows file paths may need to be adjusted. + +## Backend + +### 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`. + +### Linting + +To lint, run `./gradlew spotlessApply` and `wpiformat`. + +## Documentation + +### Installation + +To install `doc8`, the python tool we use to lint our documentation, run `pipx install doc8`. + +### Linting + +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. + +``` +alias pvLint='wpiformat -v && ./gradlew spotlessApply && prettier --write photon-client/* --ignore-path photon-client/.prettierignore && doc8 docs' +``` From eb2f66dbb603f1b039ad37049fea36484fe70525 Mon Sep 17 00:00:00 2001 From: samfreund Date: Thu, 30 Oct 2025 12:36:15 -0500 Subject: [PATCH 2/7] use defined commands for client linting --- docs/source/docs/contributing/linting.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/source/docs/contributing/linting.md b/docs/source/docs/contributing/linting.md index baa5ba162c..e5c1134e27 100644 --- a/docs/source/docs/contributing/linting.md +++ b/docs/source/docs/contributing/linting.md @@ -2,13 +2,9 @@ ## Frontend -### Installation - -In order to lint the frontend, it's necessary to install `prettier`. This can be done by running `npm install prettier --global`. - ### Linting -In order to lint the frontend, run `prettier --write photon-client/* --ignore-path photon-client/.prettierignore`. This should be done from the base level of the repo. The command above is meant for linux, if you're using Windows file paths may need to be adjusted. +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 @@ -35,5 +31,5 @@ To lint the documentation, run `doc8 docs` from the root level of the docs. 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. ``` -alias pvLint='wpiformat -v && ./gradlew spotlessApply && prettier --write photon-client/* --ignore-path photon-client/.prettierignore && doc8 docs' +alias pvLint='wpiformat -v && ./gradlew spotlessApply && pnpm -C photon-client lint && pnpm -C photon-client format && doc8 docs' ``` From 2931eae422083a1e4c032ba9b24d272d585bce35 Mon Sep 17 00:00:00 2001 From: samfreund Date: Fri, 31 Oct 2025 15:05:48 -0500 Subject: [PATCH 3/7] add version instructions --- docs/source/docs/contributing/linting.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/source/docs/contributing/linting.md b/docs/source/docs/contributing/linting.md index e5c1134e27..90361d96c3 100644 --- a/docs/source/docs/contributing/linting.md +++ b/docs/source/docs/contributing/linting.md @@ -1,5 +1,9 @@ # Linting the PhotonVision Codebase +## Versions + +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 @@ -10,7 +14,7 @@ In order to lint the frontend, run `pnpm -C photon-client lint && pnpm -C photon ### 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 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 @@ -20,7 +24,7 @@ To lint, run `./gradlew spotlessApply` and `wpiformat`. ### Installation -To install `doc8`, the python tool we use to lint our documentation, run `pipx install doc8`. +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 From 92b2d80a55bdfbd77a15c808c382c3bf81d93b23 Mon Sep 17 00:00:00 2001 From: samfreund Date: Fri, 31 Oct 2025 15:11:20 -0500 Subject: [PATCH 4/7] style changes --- docs/source/docs/contributing/linting.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/docs/contributing/linting.md b/docs/source/docs/contributing/linting.md index 90361d96c3..c821d0b8d8 100644 --- a/docs/source/docs/contributing/linting.md +++ b/docs/source/docs/contributing/linting.md @@ -2,31 +2,31 @@ ## Versions -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. +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 +### 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 -### Installation +### 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==`. +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 +### Linting the backend To lint, run `./gradlew spotlessApply` and `wpiformat`. ## Documentation -### Installation +### 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==`. +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 +### Linting the documentation To lint the documentation, run `doc8 docs` from the root level of the docs. From 1a5e324e96cc6619fde4f3dcf520d9513ed1284f Mon Sep 17 00:00:00 2001 From: samfreund Date: Fri, 31 Oct 2025 15:50:27 -0500 Subject: [PATCH 5/7] Add linting to PR template --- .github/pull_request_template.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 704a41b1ac..0d5211e4a4 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 From d35c4181942dce9bc409cb23d921445c6ec7d1ec Mon Sep 17 00:00:00 2001 From: samfreund Date: Sat, 1 Nov 2025 18:08:34 -0500 Subject: [PATCH 6/7] add venv comment --- docs/source/docs/contributing/linting.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/source/docs/contributing/linting.md b/docs/source/docs/contributing/linting.md index c821d0b8d8..b394820a0b 100644 --- a/docs/source/docs/contributing/linting.md +++ b/docs/source/docs/contributing/linting.md @@ -2,6 +2,10 @@ ## 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 From eaea6646cb334dbace82dc30d41ce1475c1432d3 Mon Sep 17 00:00:00 2001 From: Sam Freund Date: Sat, 1 Nov 2025 21:10:59 -0500 Subject: [PATCH 7/7] Style fixes --- docs/source/docs/contributing/linting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/docs/contributing/linting.md b/docs/source/docs/contributing/linting.md index b394820a0b..690113c687 100644 --- a/docs/source/docs/contributing/linting.md +++ b/docs/source/docs/contributing/linting.md @@ -6,7 +6,7 @@ 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. +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 @@ -16,7 +16,7 @@ In order to lint the frontend, run `pnpm -C photon-client lint && pnpm -C photon ## Backend -### Wpiformat installation +### 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==`. @@ -38,6 +38,6 @@ To lint the documentation, run `doc8 docs` from the root level of the docs. 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' ```