docs: Add project structure map for contributors by thecloudsavvy · Pull Request #1020 · antonbabenko/pre-commit-terraform

thecloudsavvy · 2026-09-14T20:40:51Z

Summary

First slice of #865: a contributor-facing project structure page (layout, shell vs Python hooks, tests) and README links. Hook usage stays in the README; PR process stays in .github/CONTRIBUTING.md.

Signed-off-by: Taiwo Abatan <thecloudsavvy@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>

coderabbitai · 2026-09-14T20:41:05Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 9c2b28dd-5b71-48dc-a3d8-e35496b6e0ea

📥 Commits

Reviewing files that changed from the base of the PR and between 7d579b4 and 0a014ca.

📒 Files selected for processing (2)

README.md
docs/project_structure.md

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

📝 Summary

Summary by CodeRabbit

Documentation
- Added project-structure documentation covering key directories, configuration files, CI workflows, hook types, and test locations.
- Added guidance for running local checks and maintaining generated changelog content.
- Updated the README table of contents and contribution section to link to the new project-structure documentation.

Walkthrough

The README now links to a new project structure guide. The guide documents repository paths, shell and Python hooks, contribution references, and local development checks.

Changes

Project structure documentation

Layer / File(s)	Summary
README project structure references `README.md`	README.md adds project structure links, a table-of-contents entry, and a section describing the documentation scope.
Project structure guide `docs/project_structure.md`	The new guide describes repository paths, shell and Python hooks, contribution references, and local development checks.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 0a014

The documentation links and repository guidance are consistent, with no executable behavior changed.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description accurately summarizes the new contributor-facing project structure documentation and README links.
Title check	✅ Passed	The title clearly identifies the main change: adding a project structure map for contributors.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Signed-off-by: Taiwo Abatan <thecloudsavvy@gmail.com>

MaxymVlasov

Great start!
I left a few comments to clarify how to make these docs even better

MaxymVlasov · 2026-09-16T15:05:57Z

+| --- | --- |
+| `hooks/` | Bash entry points (`<hook_name>.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`) |


It may make sense to specify that we use pytest also as black-box testing for shell hooks functionality

MaxymVlasov · 2026-09-16T15:10:14Z

+| `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 |


It is also used in the recently added --hooks-config=--tool-version=X.Y.Z functionality.

https://github.com/antonbabenko/pre-commit-terraform#most-hooks-pin-a-specific-tool-version
#1002

MaxymVlasov · 2026-09-16T15:12:36Z

+
+| Path | Role |
+| --- | --- |
+| `hooks/` | Bash entry points (`<hook_name>.sh`) and shared `_common.sh` |


MaxymVlasov · 2026-09-16T15:19:52Z

+| `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 |


Hmm, not sure that we need to document this 🤔

You know what - let's split this table in a few:

Bash-related

Python-related

Used by both & other

There may be more tables. Some entities may appear in multiple tables as well.
I, as contributor, would be like to understand what to touch and what to not during work with some part of project. So would be nice to decompose this table into a few groups.

MaxymVlasov · 2026-09-16T15:20:25Z

+| `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/) |


Let's mention here https://prek.j178.dev/ as well

MaxymVlasov · 2026-09-16T15:21:05Z

+
+## Hook types
+
+**Shell hooks** (most of them) live in `hooks/<hook_name>.sh`:


Suggested change

**Shell hooks** (most of them) live in `hooks/<hook_name>.sh`:

**Shell hooks** live in `hooks/<hook_name>.sh`:

MaxymVlasov · 2026-09-16T15:21:27Z

+
+## 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.


Suggested change

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.

Install pre-commit and run the repo's own hooks before you push. Python tests run with `tox -qq`. Do not hand-edit `CHANGELOG.md`; releases own that file.

docs: add project structure map for contributors

7296607

Signed-off-by: Taiwo Abatan <thecloudsavvy@gmail.com> Co-authored-by: Cursor <cursoragent@cursor.com>

thecloudsavvy requested review from MaxymVlasov, antonbabenko and yermulnik as code owners September 14, 2026 20:40

docs: include project_structure.md in the tree

0a014ca

Signed-off-by: Taiwo Abatan <thecloudsavvy@gmail.com>

yermulnik changed the title ~~docs: add project structure map for contributors~~ docs: Add project structure map for contributors Sep 14, 2026

MaxymVlasov reviewed Sep 16, 2026

View reviewed changes

Navigation Menu

Uh oh!

docs: Add project structure map for contributors - #1020

docs: Add project structure map for contributors#1020
thecloudsavvy wants to merge 2 commits into
antonbabenko:masterfrom
thecloudsavvy:docs/project-structure

thecloudsavvy commented Sep 14, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 14, 2026 •

edited

Loading

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

MaxymVlasov left a comment

Uh oh!

MaxymVlasov Sep 16, 2026

Uh oh!

MaxymVlasov Sep 16, 2026

Uh oh!

MaxymVlasov Sep 16, 2026

Uh oh!

MaxymVlasov Sep 16, 2026

Uh oh!

MaxymVlasov Sep 16, 2026

Uh oh!

MaxymVlasov Sep 16, 2026

Uh oh!

MaxymVlasov Sep 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	\| `hooks/` \| Bash entry points (`<hook_name>.sh`) and shared `_common.sh` \|
	\| `hooks/` \| Bash hooks entry points (`<hook_name>.sh`). Shared internal files starts from the undersore, e.g. `_common.sh` \|


		## Hook types

		Shell hooks (most of them) live in `hooks/<hook_name>.sh`:

	Shell hooks (most of them) live in `hooks/<hook_name>.sh`:
	Shell hooks live in `hooks/<hook_name>.sh`:


		## 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.

Uh oh!

Conversation

thecloudsavvy commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

coderabbitai Bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Uh oh!

MaxymVlasov left a comment

Choose a reason for hiding this comment

Uh oh!

MaxymVlasov Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

MaxymVlasov Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

MaxymVlasov Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

MaxymVlasov Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

MaxymVlasov Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

MaxymVlasov Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

MaxymVlasov Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

thecloudsavvy commented Sep 14, 2026 •

edited

Loading

coderabbitai Bot commented Sep 14, 2026 •

edited

Loading