Skip to content

docs: standardize PR template + CONTRIBUTING (hopper-lens pass) #132

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jpleva91 merged 1 commit into from
Apr 13, 2026
Merged

docs: standardize PR template + CONTRIBUTING (hopper-lens pass) #132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<!--
Keep this short. A tired reviewer at 11pm should grok it in 30 seconds.
Delete sections that don't apply. Don't add new ones.
-->

## Summary
<!-- 1-3 sentences. What does this PR do, in plain language? -->

## What changed
- <!-- bulleted facts; one change per bullet -->

## Why now
<!-- One line. Link an issue or motivation. e.g. "Fixes #123" or "Unblocks rollout N." -->

## How to verify
```
# commands a reviewer can paste
```
Expected: <!-- what they should see -->

## Risks / follow-ups
<!-- Be honest. "None known" is a valid answer. List follow-up issues if any. -->

## Related
<!-- PRs, issues, umbrella work. Delete if none. -->
51 changes: 51 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Contributing

Thanks for showing up. This doc exists so your first PR lands without a scavenger hunt.

## Setup

```bash
git clone <this-repo>
cd <repo>
# Chitin-platform repos: `chitin init` bootstraps deps
# Go repos: `go build ./...`
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Go setup guidance here only mentions go build ./..., but this repo’s documented dev workflow includes building ./cmd/shellforge/ plus running tests and lint (README.md:185-188). Updating this section to reflect the repo’s actual build/test commands will reduce “it builds but fails CI” first-PR friction.

Suggested change
# Go repos: `go build ./...`
# Go repos:
# go build ./cmd/shellforge/
# go test ./...
# golangci-lint run

Copilot uses AI. Check for mistakes.
# Python repos: `uv sync` or `pip install -e .`
```

If setup takes more than one command and a coffee, that's a bug — file an issue.

## PR naming

We use [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <summary>
```

Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `perf`.

Real examples from this org:

- `feat(session): enrich triple with SoulContext`
- `fix(hook): tag governance events with active soul`
- `docs: add claws wrapper to GETTING_STARTED`

Scope is optional but helps reviewers route. Keep the summary under 70 chars.

## PR template

`.github/PULL_REQUEST_TEMPLATE.md` fills in when you open a PR. It's short on purpose. If a section doesn't apply, delete it. If you feel like adding a section, don't — open an issue instead.

## Review flow

1. CI + Copilot review run automatically on open.
2. Address Copilot comments before requesting human review (most are legit).
Comment on lines +41 to +42
Copy link

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The review automation described here references “Copilot review”, but this repo’s automated PR review workflow is “Claude Code Review” (.github/workflows/claude-code-review.yml). Consider updating the wording to match what actually runs (or use a tool-agnostic phrase like “automated code review”).

Suggested change
1. CI + Copilot review run automatically on open.
2. Address Copilot comments before requesting human review (most are legit).
1. CI + automated code review run automatically on open.
2. Address automated review comments before requesting human review (most are legit).

Copilot uses AI. Check for mistakes.
3. A human reviewer merges. Squash-merge is the default.

## Optional: soul context

If you wrote the PR under a specific cognitive lens (e.g. `hopper`, `feynman`, `turing`), mention it in the Summary. It's a hint for reviewers, not a requirement.

## Questions

Open an issue or ping in the workspace chat. Silent struggles help no one.
Loading