Add a pre-commit configuration file

[namurphy]

This PR adds a configuration file for pre-commit including several of the supported hooks. We would also need to activate pre-commit.ci for the repo so that it gets run on PRs.

The main hook we should add is codespell. A bunch of the other ones are pretty optional. The YAML checks are primarily for the file I'm adding here, and the GitHub workflow checks are added pre-emptively we might add GitHub workflows (i.e., a GitHub Action that would post a checklist to pull requests or one that would automatically label PRs).

I still need to add a Markdown/CommonMark hook...but I might want to save that to a different PR since there are a few options and I'm entirely unfamiliar with all of them.

[jtniehof]

It looks like this has a lot of unrelated / nonfunctional (?) changes, like differences in interpretation of json pretty-print and de-Unicoding the standards (which, don't get me wrong, I'm in favor of normally :) ). Is this basically to make the hooks happy with the current repo state? It makes me itchy to touch standards.md in the process of setting up commit hooks but we do have the doi as the actual version-of-record.

[namurphy]

It looks like this has a lot of unrelated / nonfunctional (?) changes, like differences in interpretation of json pretty-print and de-Unicoding the standards (which, don't get me wrong, I'm in favor of normally :) ). Is this basically to make the hooks happy with the current repo state? It makes me itchy to touch standards.md in the process of setting up commit hooks but we do have the doi as the actual version-of-record.

Correct, these are automatic fixes that were applied by doing pre-commit run --all-files. Since the meaning of the standards is exactly the same between the DOI version and this branch, I think it'd be okay to make the changes here.

[sapols]

I'm less itchy about the changes to standards.md. Like we should be spelling "alphabetical" correctly. Lol

[jtniehof]

I should lead with, yes I think we should do this!

Since the meaning of the standards is exactly the same between the DOI version and this branch, I think it'd be okay to make the changes here.

At some point where you go from not enforcing things to enforcing them, there's going to be a single terrible commit where it all lands in one place*. The version-of-record for the standards is the DOI and that isn't changing, so was asking primarily for clarification not to object.

A more substantive question: I'm familiar with git pre commit hooks which run client-side. This is obviously quite different. Can you give the tl;dr on what happens where and when? People are encouraged to fork and install the pre-commit hooks on their local clone? What happens if they don't--is the PR flagged as failing checks, or is it rewritten on GH? Do we need a readme or contributor's update?

[nabobalis]

Is there any desire to get this updated and merged?

I am happy to take the lead if need be.

[nabobalis]

This might be worth as a global exclude?

[namurphy]

Good call!

[nabobalis]

Should we switch to typos? :P

[namurphy]

I was thinking about it!

[nabobalis]

A more substantive question: I'm familiar with git pre commit hooks which run client-side. This is obviously quite different. Can you give the tl;dr on what happens where and when? People are encouraged to fork and install the pre-commit hooks on their local clone? What happens if they don't--is the PR flagged as failing checks, or is it rewritten on GH? Do we need a readme or contributor's update?

The easiest thing is to add the pre commit application. It will run the pre-commit and fail if any changes in the PR fail. Then you have two choices, you can make the bot autofix (I wouldn't recommend that) or you can have the author or the editors ask to fix the pull request (assuming that's always possible, really depends on the pre-commit config). That way the authors don't have to install anything locally.

How I use pre commit is to install the package and run it manually before I commit, I don't usually install the git hook.

[sapols]

Sorry this completely fell off my radar! I see the activity that's happened since I self-requested review. Would you say it's about ready to merge?

@namurphy this is a new concept for me, so I went to my good ol' pal ChatGPT to explain it to me. Would you call these explanations correct?

The following checks would be added by this PR:

1. Trailing Whitespace: Removes trailing whitespace from lines.
2. Case Conflict: Detects case conflicts in filenames.
3. End-of-File Fixer: Ensures files end with a newline.
4. Check YAML: Validates YAML file structure.
5. Merge Conflict: Detects unresolved Git merge conflicts.
6. Fix Smart Quotes: Converts smart quotes to straight quotes.
7. Fix Spaces: Removes excessive spaces.
8. Fix Ligatures: Replaces ligatures with individual characters.
9. Forbid BiDi Controls: Detects bidirectional text control characters.
10. Unicode Replacement Char: Detects Unicode replacement characters (�).
11. Pretty Format YAML: Formats YAML files consistently.
12. Check GitHub Workflows: Validates GitHub workflow files.
13. Typos: Detects and fixes typos in the codebase.

And when I asked what would get changed automatically vs not:

Automatic Code Alteration vs. Warnings:

• Automatically alter code:

• Trailing Whitespace removal.

• End-of-File fixer.

• Pretty-format YAML (autofixes YAML formatting).

• Smart quotes, ligatures, and spaces will be automatically fixed (from texthooks).

• Raise warnings (no auto-fix):

• Case conflict detection.

• Merge conflict detection.

• Unicode replacement character detection.

• BiDi controls detection.

• GitHub workflow file validation.

• Typos detection (it might suggest corrections, but not auto-fix).

If that's all correct, I don't have a problem with any of it and would be down to merge.

Wait, to be clear: Would these checks just be run any time a new PR was opened to this repo? Or would it run other times?

[nabobalis]

Currently it won't be run at all.

There are two choices:

1. Add a GitHub Actions that will run it on PRs and merges.
2. Add the pre-commit GitHub application to the pyhc org. It will also run on PRs and does let you add a comment to autofix any problems that are possible to autofix.

[sapols]

Ah I see. Thanks @nabobalis. So step 1 would be merge this then step 2 would be pick one of those choices for how to use it? If so that's all the more reason to merge this I think.

[nabobalis]

I think someone should decide how people want to interact with it before the merge but that can be later on.