chore(contrib): add CODEOWNERS and team workflow docs (#2286)
* chore(contrib): add commit-msg hook, CODEOWNERS, team workflow docs - Extend install-hooks.sh with commit-msg hook that enforces Conventional Commits format on every commit - Add .github/CODEOWNERS mapping packages, CI, scripts, and security-sensitive files to @gsd-build/maintainers - CONTRIBUTING.md: add Branching and commits section with naming convention, commit format, and rebase guidance - CONTRIBUTING.md: add Working with GSD section covering mode: team, unique milestone IDs, and worktree isolation for multi-dev workflows - CONTRIBUTING.md: surface npm run secret-scan:install-hook in Local development with explanation of both hooks it installs - CONTRIBUTING.md: align AI disclosure section — no AI tool authorship in commits, Draft PR requirement for multi-phase agent work * chore: remove install-hooks.sh — local git hook installation is too intrusive for a contributor PR
This commit is contained in:
Jeremy McSpadden
GitHub
parent
7a413bb84f
commit
9153506fba
3 changed files with 99 additions and 35 deletions
36
.github/CODEOWNERS
vendored
Normal file
36
.github/CODEOWNERS
vendored
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
# CODEOWNERS
|
||||
# Defines required reviewers per path. GitHub enforces these on PRs.
|
||||
# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
|
||||
#
|
||||
# Format: <pattern> <@user or @org/team>
|
||||
# Last matching rule wins.
|
||||
|
||||
# Default: maintainers review everything not explicitly matched below
|
||||
* @gsd-build/maintainers
|
||||
|
||||
# Core agent orchestration — RFC required, senior review only
|
||||
packages/pi-agent-core/ @gsd-build/maintainers
|
||||
src/resources/extensions/gsd/ @gsd-build/maintainers
|
||||
|
||||
# AI/LLM provider integrations
|
||||
packages/pi-ai/ @gsd-build/maintainers
|
||||
|
||||
# Terminal UI
|
||||
packages/pi-tui/ @gsd-build/maintainers
|
||||
|
||||
# Native bindings — platform-specific, needs careful review
|
||||
native/ @gsd-build/maintainers
|
||||
|
||||
# CI/CD and release pipeline — high blast radius
|
||||
.github/ @gsd-build/maintainers
|
||||
scripts/ @gsd-build/maintainers
|
||||
Dockerfile @gsd-build/maintainers
|
||||
|
||||
# Security-sensitive files — always require maintainer sign-off
|
||||
.secretscanignore @gsd-build/maintainers
|
||||
scripts/secret-scan.sh @gsd-build/maintainers
|
||||
scripts/install-hooks.sh @gsd-build/maintainers
|
||||
|
||||
# Contributor-facing docs — keep accurate, maintainers approve
|
||||
CONTRIBUTING.md @gsd-build/maintainers
|
||||
VISION.md @gsd-build/maintainers
|
||||
|
|
@ -11,6 +11,59 @@ Read [VISION.md](VISION.md) before contributing. It defines what GSD-2 is, what
|
|||
3. **No issue? Create one first** for new features. Bug fixes for obvious problems can skip this step.
|
||||
4. **Architectural changes require an RFC.** If your change touches core systems (auto-mode, agent-core, orchestration), open an issue describing your approach and get approval before writing code. We use Architecture Decision Records (ADRs) for significant decisions.
|
||||
|
||||
## Branching and commits
|
||||
|
||||
Always work on a dedicated branch. Never push directly to `main`.
|
||||
|
||||
**Branch naming:** `<type>/<short-description>`
|
||||
|
||||
| Type | When to use |
|
||||
|------|-------------|
|
||||
| `feat/` | New functionality |
|
||||
| `fix/` | Bug or defect correction |
|
||||
| `refactor/` | Code restructuring, no behavior change |
|
||||
| `test/` | Adding or updating tests |
|
||||
| `docs/` | Documentation only |
|
||||
| `chore/` | Dependencies, tooling, housekeeping |
|
||||
| `ci/` | CI/CD configuration |
|
||||
|
||||
**Commit messages** must follow [Conventional Commits](https://www.conventionalcommits.org/). The commit-msg hook enforces this locally; CI enforces it on push.
|
||||
|
||||
```
|
||||
<type>(<scope>): <short summary>
|
||||
```
|
||||
|
||||
Valid types: `feat` `fix` `docs` `chore` `refactor` `test` `infra` `ci` `perf` `build` `revert`
|
||||
|
||||
```
|
||||
feat(pi-agent-core): add streaming output for long-running tasks
|
||||
fix(pi-ai): resolve null pointer on empty provider response
|
||||
chore(deps): bump typescript from 5.3.0 to 5.4.2
|
||||
```
|
||||
|
||||
Keep branches current by rebasing onto `main` — do not merge `main` into your feature branch:
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
```
|
||||
|
||||
## Working with GSD (team workflow)
|
||||
|
||||
GSD uses worktree-based isolation for multi-developer work. If you're contributing with GSD running, enable team mode in your project preferences:
|
||||
|
||||
```yaml
|
||||
# .gsd/preferences.md
|
||||
---
|
||||
version: 1
|
||||
mode: team
|
||||
---
|
||||
```
|
||||
|
||||
This enables unique milestone IDs, branch pushing, and pre-merge checks — preventing milestone ID collisions when multiple contributors run auto-mode simultaneously. Each developer gets their own isolated worktree; squash merges to `main` happen independently.
|
||||
|
||||
For full details see [docs/working-in-teams.md](docs/working-in-teams.md) and [docs/git-strategy.md](docs/git-strategy.md).
|
||||
|
||||
## Opening a pull request
|
||||
|
||||
### PR description format
|
||||
|
|
@ -65,10 +118,12 @@ If your PR changes any public API, CLI behavior, config format, or file structur
|
|||
|
||||
AI-generated PRs are first-class citizens here. We welcome them. We just ask for transparency:
|
||||
|
||||
- **Disclose it.** Note that the PR is AI-assisted in your description.
|
||||
- **Disclose it.** Note that the PR is AI-assisted in your description. Do not credit the AI tool as an author or co-author in the commit or PR.
|
||||
- **Test it.** AI-generated code must be tested to the same standard as human-written code. "The AI said it works" is not a test plan.
|
||||
- **Understand it.** You should be able to explain what the code does and why. If a reviewer asks a question, "I'll ask the AI" is not an answer.
|
||||
|
||||
AI agents opening PRs must follow the same workflow as human contributors: clean working tree, new branch per task, CI passing before requesting review. Multi-phase work should start as a Draft PR and only move to Ready when complete.
|
||||
|
||||
AI PRs go through the same review process as any other PR. No special treatment in either direction.
|
||||
|
||||
## Architecture guidelines
|
||||
|
|
@ -109,6 +164,9 @@ PRs go through automated review first, then human review. To help us review effi
|
|||
# Install dependencies
|
||||
npm ci
|
||||
|
||||
# Install git hooks (secret scanning + commit message validation)
|
||||
npm run secret-scan:install-hook
|
||||
|
||||
# Build
|
||||
npm run build
|
||||
|
||||
|
|
@ -119,6 +177,10 @@ npm test
|
|||
npx tsc --noEmit
|
||||
```
|
||||
|
||||
Run `npm run secret-scan:install-hook` once after cloning. It installs two hooks:
|
||||
- **pre-commit** — blocks commits containing hardcoded secrets or credentials
|
||||
- **commit-msg** — validates Conventional Commits format before the commit lands
|
||||
|
||||
CI must pass before your PR will be reviewed. Run these locally to save time.
|
||||
|
||||
## Security
|
||||
|
|
|
|||
|
|
@ -1,34 +0,0 @@
|
|||
#!/usr/bin/env bash
|
||||
# Installs the git pre-commit hook for secret scanning.
|
||||
# Safe to run multiple times — only installs if not already present.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
HOOK_DIR="$(git rev-parse --git-dir)/hooks"
|
||||
HOOK_FILE="$HOOK_DIR/pre-commit"
|
||||
MARKER="# gsd-secret-scan"
|
||||
|
||||
mkdir -p "$HOOK_DIR"
|
||||
|
||||
# Check if our hook is already installed
|
||||
if [[ -f "$HOOK_FILE" ]] && grep -q "$MARKER" "$HOOK_FILE" 2>/dev/null; then
|
||||
echo "secret-scan pre-commit hook already installed."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# If a pre-commit hook already exists, append; otherwise create
|
||||
if [[ -f "$HOOK_FILE" ]]; then
|
||||
echo "" >> "$HOOK_FILE"
|
||||
echo "$MARKER" >> "$HOOK_FILE"
|
||||
echo 'bash "$(git rev-parse --show-toplevel)/scripts/secret-scan.sh"' >> "$HOOK_FILE"
|
||||
echo "secret-scan appended to existing pre-commit hook."
|
||||
else
|
||||
cat > "$HOOK_FILE" << 'EOF'
|
||||
#!/usr/bin/env bash
|
||||
# gsd-secret-scan
|
||||
# Pre-commit hook: scan staged files for hardcoded secrets
|
||||
bash "$(git rev-parse --show-toplevel)/scripts/secret-scan.sh"
|
||||
EOF
|
||||
chmod +x "$HOOK_FILE"
|
||||
echo "secret-scan pre-commit hook installed."
|
||||
fi
|
||||
Loading…
Add table
Reference in a new issue