Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a pre-commit configuration file #23

Open
wants to merge 20 commits into
base: main
Choose a base branch
from

Conversation

namurphy
Copy link
Contributor

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.

@namurphy namurphy marked this pull request as draft October 24, 2023 18:03
@namurphy namurphy marked this pull request as ready for review October 24, 2023 18:12
@jtniehof
Copy link
Contributor

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
Copy link
Contributor Author

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.

@namurphy namurphy closed this Oct 24, 2023
@namurphy namurphy reopened this Oct 24, 2023
@sapols sapols self-requested a review October 27, 2023 15:54
@sapols
Copy link
Contributor

sapols commented Oct 27, 2023

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

@jtniehof
Copy link
Contributor

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
Copy link

Is there any desire to get this updated and merged?

I am happy to take the lead if need be.

hooks:
- id: codespell
args: [--write-changes]
exclude: .*\.dot|.*\.svg

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might be worth as a global exclude?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call!

hooks:
- id: check-github-workflows

- repo: https://github.com/codespell-project/codespell

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we switch to typos? :P

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking about it!

@nabobalis
Copy link

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
Copy link
Contributor

sapols commented Sep 18, 2024

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
Copy link

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
Copy link
Contributor

sapols commented Sep 18, 2024

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
Copy link

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

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.

4 participants