docs: add suggested pre-commit config

[jriddy]

Adds a section describing a possible working pre-commit config, using pass_filenames and --unmatched-cli-globs=ignore

[sureshjoshi]

Question on this: Is this for use cases where pre-commit is already in use for the repo?
Secondary question: Do we have anywhere in the docs (outside of Pants contribution info) specifying how to create a basic git hook? Ala https://sureshjoshi.com/development/pants-plugin-code-quality#pre-commit-hooks

[jriddy]

Question on this: Is this for use cases where pre-commit is already in use for the repo?

Yeah that was the intention

Secondary question: Do we have anywhere in the docs (outside of Pants contribution info) specifying how to create a basic git hook? Ala https://sureshjoshi.com/development/pants-plugin-code-quality#pre-commit-hooks

No, perhaps we should add this. That would be a more natural place for this than CI docs. We could mention hand-rolling hooks like you described or using tools like pre-commit dot com as well.

Mostly I want to highlight the gotchyas around using the --changed-*family of options when dealing with unstaged files and potentially re-named refs in local repos, as well as Pants' behaviors when handling globs it doesn't recognize. But a whole pre-commit, or better yet, "How to help developers test locally" section might be warranted.

[jriddy]

Btw, how do I add a category label? Is that a right given only to maintainers?

[stuhood]

Btw, how do I add a category label? Is that a right given only to maintainers?

Contributors can as well: I'll ping you about that offline.

[Eric-Arellano]

Thanks!

[Eric-Arellano]

Suggested change

However, using `--changed-since=origin/main` is not as useful locally. Developers my have unstaged or untracked files lying around in their working directory, or their Git references may be out of date or named differently than the ones you use in CI. Instead, it's better to leverage pre-commit's ability to pass changed filenames to commands to Pants, and tell Pants to ignore files it's been told not to track:

However, using `--changed-since=origin/main` is not as useful locally. Developers my have unstaged or untracked files lying around in their working directory, or their Git references may be out of date or named differently than the ones you use in CI. Instead, it's often better to leverage pre-commit's ability to pass changed filenames to commands to Pants, and tell Pants to ignore files it's been told not to track:

[Eric-Arellano]

This means H2, and it makes the H3 for "### Tuning resource consumption (advanced)" in the wrong place. Maybe keep it as H2 but move to lower in the file?