Skip to content

Commit 7751331

Browse files
marcio-bmarcio-b
committed
docs: add contributing guidelines and pull request template
1 parent bd7c3d1 commit 7751331

2 files changed

Lines changed: 169 additions & 0 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
## Description
2+
3+
<!-- What does this PR do? Why is it needed? Be concise but complete.
4+
Link any related issues with "Closes #123" or "Fixes #123". -->
5+
6+
## Type of change
7+
8+
<!-- Check all that apply -->
9+
10+
- [ ] `fix:` — Bug fix (patch version bump)
11+
- [ ] `feat:` — New feature (minor version bump)
12+
- [ ] `feat!:` / `fix!:` — Breaking change (major version bump)
13+
- [ ] `docs:` — Documentation only (no version bump)
14+
- [ ] `chore:` — Maintenance or config (no version bump)
15+
- [ ] `refactor:` — Code restructure, no behaviour change (no version bump)
16+
17+
## Changes made
18+
19+
<!-- List the specific files changed and what was done to each.
20+
This helps reviewers know where to focus. -->
21+
22+
-
23+
-
24+
25+
## Testing
26+
27+
<!-- How did you verify this works? What edge cases did you consider? -->
28+
29+
- [ ] `bash -n hook/pre-push` passes with no output
30+
- [ ] `bash -n install.sh` passes with no output
31+
- [ ] Manually tested the hook on a real repository
32+
- [ ] Tested on macOS
33+
- [ ] Tested on Linux
34+
35+
## Checklist
36+
37+
- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org)
38+
- [ ] No `eval`, heredoc variable expansion, or unquoted variable interpolation in shell scripts
39+
- [ ] File lists passed as arrays, never as interpolated strings
40+
- [ ] `VERSION`, `CHANGELOG.md`, `.release-please-manifest.json`, and `release-please-config.json` were **not** manually edited — these are managed by release-please
41+
- [ ] New template added to the table in `README.md` _(if applicable)_
42+
- [ ] New template name added to `install.sh` usage comment _(if applicable)_
43+
44+
## Screenshots / output
45+
46+
<!-- If your change affects terminal output, paste a before/after example here. -->

‎CONTRIBUTING.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Contributing to ai-git-hooks
2+
3+
Thank you for your interest in contributing! This document covers everything
4+
you need to know to get changes merged.
5+
6+
---
7+
8+
## How to contribute
9+
10+
All changes — including from maintainers — must go through a pull request. Direct pushes to `main` are not allowed. Every PR runs automated checks via GitHub Actions to validate shell syntax and script integrity before merging.
11+
12+
---
13+
14+
## Development setup
15+
16+
```bash
17+
git clone git@github.com:rootstrap/ai-git-hooks.git
18+
cd ai-git-hooks
19+
```
20+
21+
No dependencies to install — the project is pure shell scripts and YAML.
22+
23+
---
24+
25+
## Commit messages
26+
27+
This project uses [Conventional Commits](https://www.conventionalcommits.org).
28+
`release-please` reads your commit messages to determine version bumps and
29+
generate the changelog automatically, so following the convention is important.
30+
31+
| Prefix | When to use | Version bump |
32+
|---|---|---|
33+
| `fix:` | Bug fix in the hook or installer | Patch |
34+
| `feat:` | New feature or template | Minor |
35+
| `feat!:` or `fix!:` | Breaking change | Major |
36+
| `docs:` | Documentation only | None |
37+
| `chore:` | Maintenance, config, CI | None |
38+
| `refactor:` | Code restructure, no behaviour change | None |
39+
40+
Examples:
41+
```
42+
feat: add python template
43+
fix: handle filenames with spaces in tool runner
44+
docs: add troubleshooting section to README
45+
feat!: require Claude Code CLI — remove fallback to allow push
46+
```
47+
48+
---
49+
50+
## What you can contribute
51+
52+
### Adding a new template
53+
54+
Templates live in `templates/` and are downloaded by `install.sh` when a user
55+
passes `--template <name>`. To add one:
56+
57+
1. Create `templates/<name>.yml` based on an existing template
58+
2. Populate the `tools:` section with the stack's standard linters and test runners
59+
3. Add appropriate `ignore_paths:` for generated or vendored files
60+
4. Add a row to the templates table in `README.md`
61+
5. Add the new template name to the `--template` usage comment in `install.sh`
62+
63+
Keep templates self-contained — no inheritance, no references to other files.
64+
Each template should be a ready-to-use starting point that a developer can
65+
commit as-is and customise from there.
66+
67+
### Fixing the hook script
68+
69+
`hook/pre-push` has been hardened over many iterations. Before making changes:
70+
71+
- Run `bash -n hook/pre-push` to validate syntax before committing
72+
- Avoid `eval`, heredoc variable expansion, and unquoted variable interpolation
73+
- File lists must always be passed as arrays, never as interpolated strings
74+
- Test on both macOS (BSD tools) and Linux (GNU tools) if possible — `sed`,
75+
`grep`, and `printf` behave differently between them
76+
77+
### Fixing the installer
78+
79+
`install.sh` follows the same shell safety rules as the hook. Additionally:
80+
- It must work when piped through `bash` (`curl ... | bash`)
81+
- It must not assume any tools beyond `bash`, `curl`, and `git` are available
82+
83+
---
84+
85+
## Testing your changes
86+
87+
There is no automated test suite yet. To test manually:
88+
89+
```bash
90+
# Validate shell syntax
91+
bash -n hook/pre-push
92+
bash -n install.sh
93+
94+
# Test the installer locally (from inside a git repo)
95+
bash install.sh --template node
96+
97+
# Test the hook by installing it and making a push
98+
bash install.sh --template node
99+
git push
100+
```
101+
102+
For template changes, install the template into a representative project and
103+
verify the configured tools run correctly against changed files.
104+
105+
---
106+
107+
## Pull request checklist
108+
109+
- [ ] `bash -n hook/pre-push` passes with no output
110+
- [ ] `bash -n install.sh` passes with no output
111+
- [ ] Commit messages follow Conventional Commits
112+
- [ ] New templates include all keys from an existing template
113+
- [ ] `README.md` updated if a new template was added
114+
- [ ] `install.sh` usage comment updated if a new template was added
115+
116+
---
117+
118+
## Releases
119+
120+
Releases are fully automated via `release-please`. When your PR is merged to
121+
`main`, release-please analyses the commit messages and opens a Release PR if
122+
there is anything releasable. Merging the Release PR creates the GitHub Release
123+
and git tag automatically — you don't need to do anything manually.

0 commit comments

Comments
 (0)