From 7296607686f3515dd991be6e872cdcec12f0cede Mon Sep 17 00:00:00 2001 From: Taiwo Abatan Date: Mon, 14 Sep 2026 21:40:44 +0100 Subject: [PATCH 1/2] docs: add project structure map for contributors Signed-off-by: Taiwo Abatan Co-authored-by: Cursor --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fd647dae2..373941552 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,8 @@ It can be run: * For the entire repository or just for change-related files (e.g., local git stash, last commit, or all changes in a Pull Request) Want to contribute? -Check [open issues](https://github.com/antonbabenko/pre-commit-terraform/issues?q=label%3A%22good+first+issue%22+is%3Aopen+sort%3Aupdated-desc) +Check [open issues](https://github.com/antonbabenko/pre-commit-terraform/issues?q=label%3A%22good+first+issue%22+is%3Aopen+sort%3Aupdated-desc), +[project structure](docs/project_structure.md), and [contributing notes](/.github/CONTRIBUTING.md). [Latest Github tag]: https://img.shields.io/github/tag/antonbabenko/pre-commit-terraform.svg @@ -42,6 +43,7 @@ If you want to support the development of `pre-commit-terraform` and [many other * [Sponsors](#sponsors) * [Table of content](#table-of-content) +* [Project structure](#project-structure) * [How to install](#how-to-install) * [1. Install dependencies](#1-install-dependencies) * [1.1 Custom Terraform binaries and OpenTofu support](#11-custom-terraform-binaries-and-opentofu-support) @@ -85,6 +87,10 @@ If you want to support the development of `pre-commit-terraform` and [many other * [License](#license) * [Additional information for users from Russia and Belarus](#additional-information-for-users-from-russia-and-belarus) +## Project structure + +See [docs/project_structure.md](docs/project_structure.md) for the directory layout, the two hook types (shell vs Python), and where tests live. + ## How to install ### 1. Install dependencies From 0a014ca0516e3ff47df75cbbf707b59a517b3fd7 Mon Sep 17 00:00:00 2001 From: Taiwo Abatan Date: Mon, 14 Sep 2026 21:41:10 +0100 Subject: [PATCH 2/2] docs: include project_structure.md in the tree Signed-off-by: Taiwo Abatan --- docs/project_structure.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/project_structure.md diff --git a/docs/project_structure.md b/docs/project_structure.md new file mode 100644 index 000000000..2ef45e393 --- /dev/null +++ b/docs/project_structure.md @@ -0,0 +1,36 @@ +# Project structure + +This is a map of the repository for contributors. Hook *usage* stays in the [README](../README.md). How to add a hook, run tests, and open a PR is in [`.github/CONTRIBUTING.md`](../.github/CONTRIBUTING.md). + +## Layout + +| Path | Role | +| --- | --- | +| `hooks/` | Bash entry points (`.sh`) and shared `_common.sh` | +| `src/pre_commit_terraform/` | Python package: CLI parsing, env expansion, `__GIT_WORKING_DIR__`, `terraform_docs_replace` | +| `tests/pytest/` | Python unit tests (`pytest`) | +| `tools/entrypoint.sh` | Docker image entrypoint | +| `tools/install/` | Per-tool install scripts used when building the Docker image | +| `dependencies/lock-files/` | Pinned Python constraints for reproducible image builds | +| `.pre-commit-hooks.yaml` | Hook definitions consumed by the [pre-commit framework](https://pre-commit.com/) | +| `pyproject.toml` / `hatch.toml` | Python project and build config | +| `tox.ini` | Test environment matrix | +| `.github/workflows/ci-cd.yml` | PR checks, tox, image build; release on merge to `master` | + +## Hook types + +**Shell hooks** (most of them) live in `hooks/.sh`: + +- Source `_common.sh` for `--args`, `--hook-config`, `--env-vars`, env expansion, `__GIT_WORKING_DIR__`, parallelism, and `terraform init` +- Define `per_dir_hook_unique_part()` for per-directory work +- Call `common::per_dir_hook` instead of splitting arguments by hand + +**Python hooks** run as `python -m pre_commit_terraform `: + +- Modules live under `src/pre_commit_terraform/` +- Each subcommand implements `invoke_cli_app()`, `populate_argument_parser()`, and `CLI_SUBCOMMAND_NAME` +- Register new subcommands in `_cli_subcommands.py` and add a hook entry in `.pre-commit-hooks.yaml` + +## Local checks + +Install pre-commit and run the repo's own hooks before you push. Python tests run with `tox`. Do not hand-edit `CHANGELOG.md`; releases own that file.