Skip to content

docs: point CONTRIBUTING at the tooling the repo actually uses - #1665

Merged
MODSetter merged 1 commit into
MODSetter:devfrom
Yigtwxx:docs/contributing-tooling
Aug 7, 2026
Merged

docs: point CONTRIBUTING at the tooling the repo actually uses#1665
MODSetter merged 1 commit into
MODSetter:devfrom
Yigtwxx:docs/contributing-tooling

Conversation

@Yigtwxx

@Yigtwxx Yigtwxx commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

The Code Quality section of CONTRIBUTING.md sends a new contributor to a file that is not in the repository, and then names two formatters the project does not use.

Description

Both problems are in the same twelve lines, which is why they are one PR.

The dead link. CONTRIBUTING.md:105 reads "See our detailed Pre-commit Guide". PRE_COMMIT.md does not exist — git ls-files has no match, and that line is the only reference to it anywhere in the repo, so it is not a file that moved. This is step 1 of the first section a contributor is told to complete before writing code, so the first instruction in the onboarding path is a 404.

The formatter names. CONTRIBUTING.md:112 says "Black for Python, Prettier for TypeScript". Neither is configured:

claimed actually configured
Python Black ruff + ruff-format (.pre-commit-config.yaml, [tool.ruff] in surfsense_backend/pyproject.toml)
TypeScript Prettier biome (biome.json, run as the biome-check-web hook)

git grep -inE '\bblack\b|prettier' -- '*.toml' '*.json' '*.yaml' '*.yml' returns nothing, so this is not a case of two tools coexisting — the named ones are absent and the real ones are unnamed. The practical cost is a contributor running black . on the backend and producing a diff that ruff-format then disagrees with.

What changed

  • The dead link is replaced with the install command (pip install pre-commit && pre-commit install) and a link to .pre-commit-config.yaml. pip install pre-commit is the same invocation .github/workflows/code-quality.yml:35 uses, rather than one invented here.
  • The "understand the automated checks" line now points at that config file and gives pre-commit run --all-files. Pointing at the config rather than at prose is deliberate: the hook list is then generated from the thing being described and cannot go stale the way the deleted guide did.
  • BlackRuff, PrettierBiome.

No new documentation file is added. Writing a replacement PRE_COMMIT.md would restore the same failure mode this PR is fixing — a second description of the hooks that drifts from .pre-commit-config.yaml — and choosing to maintain one is a maintainer's call, not something to smuggle into a link repair.

Motivation and Context

No linked issue; found while contributing #1660, #1661 and #1662, all of which required reading this section first.

Screenshots

Not applicable — documentation only.

API Changes

  • This PR includes API changes

Change Type

  • Bug fix
  • New feature
  • Performance improvement
  • Refactoring
  • Documentation
  • Dependency/Build system
  • Breaking change
  • Other (specify):

Testing Performed

  • Tested locally

One file changed, 3 lines. No code, no tests, nothing executable.

Verified rather than assumed:

  • PRE_COMMIT.md absent: git ls-files has no match on dev at cc8fa6e.
  • Black and Prettier absent: the git grep above returns nothing across every tracked .toml, .json, .yaml and .yml.
  • The replacement command matches CI: .github/workflows/code-quality.yml:35 is pip install pre-commit.
  • The new relative link resolves — .pre-commit-config.yaml is at the repository root, alongside CONTRIBUTING.md.

Checklist

  • Follows project coding standards and conventions
  • Documentation updated as needed
  • Dependencies updated as needed
  • No lint/build errors or new warnings
  • All relevant tests are passing

High-level PR Summary

This PR fixes documentation errors in CONTRIBUTING.md by removing a broken link to a non-existent PRE_COMMIT.md file and correcting the formatter tool names from Black/Prettier to the actually configured tools (Ruff/Biome). The dead link is replaced with the actual installation command and a reference to .pre-commit-config.yaml, ensuring contributors can follow working instructions for setting up the development environment.

⏱️ Estimated Review Time: 5-15 minutes

💡 Review Order Suggestion
Order File Path
1 CONTRIBUTING.md

Need help? Join our Discord

The Code Quality section sends a new contributor to ./PRE_COMMIT.md, which
is not in the repository, and then names Black and Prettier as the project's
formatters. .pre-commit-config.yaml runs ruff, ruff-format and biome; neither
Black nor Prettier is configured anywhere.

Replaces the dead link with the install command and the config file itself,
so the list of hooks cannot drift out of date again, and corrects the two
formatter names.
@vercel

vercel Bot commented Aug 6, 2026

Copy link
Copy Markdown

@Yigtwxx is attempting to deploy a commit to the Rohan Verma's projects Team on Vercel.

A member of the Team first needs to authorize it.

@coderabbitai

coderabbitai Bot commented Aug 6, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b4d2bee7-2ff6-4690-8857-b0c613bb2c24

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@Yigtwxx

Yigtwxx commented Aug 6, 2026

Copy link
Copy Markdown
Contributor Author

Frontend Quality and Quality Gate are red on this PR, and neither is caused by it. The diff here is one file, CONTRIBUTING.md.

The job log reports exactly one diagnostic across the whole tree:

Checked 1055 files in 1479ms. Found 1 error.
lib/error-toast.ts:1:1 assist/source/organizeImports  FIXABLE

That file is on dev and is not touched by this branch.

A markdown-only PR reaches a TypeScript check because of how the hook is declared in .pre-commit-config.yaml: always_run: true overrides the files: ^surfsense_web/ filter, and pass_filenames: false with a trailing . in the entry means it checks the entire surfsense_web tree rather than the changed files. So the --from-ref/--to-ref narrowing in the workflow does not apply to this hook, and any PR on any path is measured against every file in surfsense_web.

This is not specific to my branch — merged PR #1663 carries the same two failures, and dev's own Code Quality runs have been failing since late July.

I have opened #1666 with the one-line sort, so it can land independently of this one. Once it does, this PR should go green on a rerun with no changes here. Happy to rebase if you would rather see it green before reviewing.

@MODSetter
MODSetter merged commit 76af571 into MODSetter:dev Aug 7, 2026
4 of 8 checks passed
@Yigtwxx
Yigtwxx deleted the docs/contributing-tooling branch August 7, 2026 06:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants