chore(dev): adopt pre-commit hooks

[2bndy5]

resolves #138

Requires the following PRs merged before review:

• style: fix lint violations about unused API #140
• chore(dev): add __init__.py files #141
• style: format python sources with ruff #142
• chore: comply with REUSE Specification #143
• chore: satisfy linting concerns from ruff #145

The pre-commit config was adapted from adafruit/Adafruit_CircuitPython_PCA9554 project's config, but with version upgrades for the specified hooks.

The added CI workflow is just something I whipped up. Maybe there's a Adafruit-maintained reusable workflow of which I'm unaware.

[tekktrik]

Some changes and requests for clarification but this is great that were almost there.

[tekktrik]

The pre-commit configuration should have the following licensing:

Suggested change

	# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
	#
	# SPDX-License-Identifier: Unlicense
	# SPDX-FileCopyrightText: 2024 Justin Myers for Adafruit Industries
	#
	# SPDX-License-Identifier: Unlicense

[tekktrik]

I don't often see this argument. Looking into it I don't think this is an issue, but I would comment why it's here so others are confused in the future (especially if authenticated git commands are required for any reason).

[2bndy5]

See rationale for zizmor's audit "artipacked" rule.

IIRC, you were the one tasked with writing Adafruit's reusable workflows, right? If so, you might want to check out zizmor.

[tekktrik]

Default permissions are fine and this doesn't need to be specified, since they are typically read-only anyways. If permissions will be specifically revoked, please provide a short comment explaining - this will save someone time in the future (e.g., the default token has permissions that would otherwise be available here that a developer is expecting in some future iteration of this workflow)

[2bndy5]

See the rationale for zizmor audit "excessive permissions" rule.

This is especially important if you're using an unverified action (directly or from a reusable/composite workflow) that automatically appropriates your env.GITHUB_TOKEN...

FYI, this aligns changes I've made to the other CI workflows in this project.

since they are typically read-only anyways

This depends on the repo settings. Forks can have different settings from upstream's settings.

please provide a short comment explaining

This is simply a best practice approach. So, the comment would be:

Suggested change

	permissions: {}
	# Do not inherit GITHUB_TOKEN permissions, for security purposes.
	# These will be explicitly granted per job (if/when needed)
	permissions: {}

this will save someone time in the future (e.g., the default token has permissions that would otherwise be available here that a developer is expecting in some future iteration of this workflow)

I'd rather be safe than sorry. If someone alters the CI with a malicious action, there's very little chance to prevent or identify the attack.

FYI, if permissions are needed but not granted (because of this line), then the runner will issue an error stating what step/action is requesting what exact permissions. This will help highlight what sacrifices you're making in the name of convenience.

[tekktrik]

I would remove this - it's fine (and desirable) to have this run on development branches.

[2bndy5]

This follows the other CI workflows' triggers in this project. Personally I perceive any failure notifications (via email or otherwise) as spam when the branch is not actually ready for review.

What you propose is very annoying for contributors who's forks have CI enabled.

[tekktrik]

Is there any reason you specifically chose 3.12? You could just specify as "3.X" and it will select the latest version.

[2bndy5]

I think it was because that is what is used in the other workflows for the project. I have no objection to using '3.x'.

It would probably make for sense to set a public variable that each workflow can use instead of updating multiple instances of with: { python-version: '3.12' }:

Suggested change

	python-version: '3.12'
	python-version: ${{ vars.python-version }}

[tekktrik]

It's your file - change yourself to the author! 😄

[tekktrik]

Regarding some similar workflow, there is a much larger one that handles things for libraries that are not applicable here (e.g., sphinx documentation and running mpy-cross), so this makes sense to break out as a standalone workflow.