From d30584270c657dd69231986cbf612c9d60465899 Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Mon, 26 May 2025 22:51:31 -0400 Subject: Tidy up `.prettierignore`. * It no longer mentions files that do not exist in this project. * It now _does_ mention files that do exist, that `prettier` should never touch, like sqlx's query- metadata JSON files, `package-lock.json`, or our bundled copies of Mermaid. --- .prettierignore | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/.prettierignore b/.prettierignore index ab78a95..325134d 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,4 +1,10 @@ -# Package Managers +# Project files package-lock.json -pnpm-lock.yaml -yarn.lock +/.sqlx/ +/docs/api/mermaid/ +/target/ + +# IDE-specific files +# +# (There's no local ignores, so it's not practical to separate these out of the project config) +/.nova/ -- cgit v1.2.3 From 1b75b5b7dfc1f3e0afa5125836d899e6f8552368 Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Mon, 26 May 2025 23:19:24 -0400 Subject: Consolidate code style checks into tool scripts. The new `tools/check-format` script checks _all_ project formatting - JS (through `prettier`), and Rust (through `rustfmt`). It also checks `prettier` against the whole project, not just against what's in the `ui` subdir, which means it now catches formatting issues in various JS config files (like `.prettierrc` itself). This commit does not include style _fixes_, which means that it does not pass its own `tools/check-format` script. This is intentional, and is intended to make the Git history a bit easier to reason about; a future commit will include format fixes. --- git-hooks/pre-commit | 5 +++-- package.json | 3 +-- tools/check-format | 11 +++++++++++ tools/reformat | 10 ++++++++++ 4 files changed, 25 insertions(+), 4 deletions(-) create mode 100755 tools/check-format create mode 100755 tools/reformat diff --git a/git-hooks/pre-commit b/git-hooks/pre-commit index 587e349..3d0ae17 100755 --- a/git-hooks/pre-commit +++ b/git-hooks/pre-commit @@ -1,8 +1,9 @@ #!/bin/bash -e # Don't put anything here that routinely takes longer than a second or so to -# run. It gets old fast. That's why this uses `cargo check` and not `cargo -# test`, for example. +# run. It gets old fast. That's why this doesn't run tests, for example. + +tools/check-format # Make sure package-lock.json is up to date with package.json npm ci --dry-run diff --git a/package.json b/package.json index 4501576..3a75fcb 100644 --- a/package.json +++ b/package.json @@ -7,8 +7,7 @@ "node": ">=22.0.0 <23.0.0" }, "scripts": { - "lint": "prettier --check ui && eslint ui", - "format": "prettier --write ui" + "lint": "eslint ui" }, "devDependencies": { "@sveltejs/adapter-static": "^3.0.8", diff --git a/tools/check-format b/tools/check-format new file mode 100755 index 0000000..3b68537 --- /dev/null +++ b/tools/check-format @@ -0,0 +1,11 @@ +#!/bin/bash -e + +## tools/check-format +## +## Verifies that the project's code conforms to the project's preferred style. Exits non-zero +## if there are style differences. + +cd "$(dirname "$0")/.." + +npx prettier --check . +cargo fmt --all --check diff --git a/tools/reformat b/tools/reformat new file mode 100755 index 0000000..4dfe7c3 --- /dev/null +++ b/tools/reformat @@ -0,0 +1,10 @@ +#!/bin/bash -e + +## tools/reformat +## +## Automatically reformats code in this project to match the project style. + +cd "$(dirname "$0")/.." + +npx prettier --write . +cargo fmt --all -- cgit v1.2.3 From d02d4fdd8e1ce85660294d89138887a5f4918e68 Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Mon, 26 May 2025 23:20:40 -0400 Subject: Document our tooling for code style. --- docs/formatting.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/formatting.md diff --git a/docs/formatting.md b/docs/formatting.md new file mode 100644 index 0000000..5339be0 --- /dev/null +++ b/docs/formatting.md @@ -0,0 +1,30 @@ +# Formatting + +We use automated tools, rather than human effort, to maintain a consistent code formatting convention, where possible. This is handled by two tools: + +- Javascript, Markdown, and JSON files are formatted using [prettier]. +- Rust is formatted using [rustfmt]. + +[prettier]: https://prettier.io + +[rustfmt]: https://doc.rust-lang.org/cargo/commands/cargo-fmt.html + +## Tools + +- To check that code formatting rules are being followed, run + `tools/check-format`. This should be run any time you're making changes, and is part of the optional + `git-hooks/pre-commit` hook script. + +- To reformat the whole project, run `tools/reformat`. + +You can also run the individual formatting tools directly. The tool scripts listed above contain the specific commands needed. + +## Formatting and code review + +Checking in changes produced solely using +`tools/reformat` or its constituent commands doesn't require review if it's the only thing you're doing. We assume that these tools make sound changes, and that the code style configured for the project is acceptable by default. + +However, formatting changes carry an outsized risk of merge conflicts, so they almost always require +_coordination_. This risk is more severe for larger formatting changes. If you make a formatting fix, it's incumbent on you to follow up on it and to assist other developers with conflicts. + +In general, we try to avoid these by fixing formatting issues before they pile up, but if you plan to commit a formatting fix, please check for outstanding work that may conflict with it. You may even want to delay or rescope formatting fixes to accommodate others' in-progress changes. -- cgit v1.2.3 From fb588fcab980db57c443812801838d1f632c8fdc Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Wed, 21 May 2025 22:33:17 -0400 Subject: Permit (and expect) trailing commas in most contexts. This is purely a stylistic preference. However, it has helped keep diffs smaller (since diffs at the end of an object or array don't require changing the last line of the array), and it's something a lot of tools and IDEs now default to expecting to. --- .prettierrc | 1 - 1 file changed, 1 deletion(-) diff --git a/.prettierrc b/.prettierrc index 3d01ccd..190fedf 100644 --- a/.prettierrc +++ b/.prettierrc @@ -1,7 +1,6 @@ { "useTabs": false, "singleQuote": true, - "trailingComma": "none", "printWidth": 100, "plugins": ["prettier-plugin-svelte"], "overrides": [{ "files": "*.svelte", "options": { "parser": "svelte" } }] -- cgit v1.2.3 From bf1ef354817dba47cc955e9654dc204f0dc07d27 Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Tue, 27 May 2025 01:36:58 -0400 Subject: Don't format coverage reports. These are ephemeral, and should not even be _considered_ by `prettier`. --- .prettierignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.prettierignore b/.prettierignore index 325134d..1ebcb2e 100644 --- a/.prettierignore +++ b/.prettierignore @@ -3,6 +3,7 @@ package-lock.json /.sqlx/ /docs/api/mermaid/ /target/ +/coverage/ # IDE-specific files # -- cgit v1.2.3