mirror of
https://github.com/sigp/lighthouse.git
synced 2026-04-25 00:38:22 +00:00
8948159a40
* Add AI assistant documentation and commands Adds structured documentation for AI coding assistants: - CLAUDE.md / AGENTS.md: Lightweight entry points with critical rules - .ai/: Shared knowledge base (CODE_REVIEW.md, DEVELOPMENT.md, ISSUES.md) - .claude/commands/: Claude Code skills for review, issue, release - .github/copilot-instructions.md: GitHub Copilot instructions Supports Claude Code, OpenAI Codex, and GitHub Copilot with modular, pointer-based structure for maintainability. Includes guidelines for AI assistants to prompt developers about updating these docs after receiving feedback, creating a continuous improvement loop. * Add parallel development tip with git worktrees * Address review feedback - Add missing details to DEVELOPMENT.md: fork-specific testing, database backends, cross-compilation targets, make test-release - Simplify AGENTS.md to pointer to CLAUDE.md (Codex can read files) * Address review feedback - Add priority signaling: Critical vs Important vs Good Practices - Restore actionable file references (canonical_head.rs, test_utils.rs, etc.) - Add Rayon CPU oversubscription context - Add tracing span guidelines - Simplify AGENTS.md to pointer * Address review feedback and remove Copilot instructions - Restore anti-patterns section (over-engineering, unnecessary complexity) - Restore design principles (simplicity first, high cohesion) - Add architecture guidance (dependency bloat, schema migrations, backwards compat) - Improve natural language guidance for AI comments - Add try_read lock pattern - Remove copilot-instructions.md (can't follow file refs, untestable)
131 lines
3.3 KiB
Markdown
131 lines
3.3 KiB
Markdown
# GitHub Issue & PR Guidelines
|
|
|
|
Guidelines for creating well-structured GitHub issues and PRs for Lighthouse.
|
|
|
|
## Issue Structure
|
|
|
|
### Start with Description
|
|
|
|
Always begin with `## Description`:
|
|
|
|
```markdown
|
|
## Description
|
|
|
|
We presently prune all knowledge of non-canonical blocks once they conflict with
|
|
finalization. The pruning is not always immediate, fork choice currently prunes
|
|
once the number of nodes reaches a threshold of 256.
|
|
|
|
It would be nice to develop a simple system for handling messages relating to
|
|
blocks that are non-canonical.
|
|
```
|
|
|
|
**Guidelines:**
|
|
- First paragraph: problem and brief solution
|
|
- Provide context about current behavior
|
|
- Link to related issues, PRs, or specs
|
|
- Be technical and specific
|
|
|
|
### Steps to Resolve (when applicable)
|
|
|
|
```markdown
|
|
## Steps to resolve
|
|
|
|
I see two ways to fix this: a strict approach, and a pragmatic one.
|
|
|
|
The strict approach would only check once the slot is finalized. This would have
|
|
0 false positives, but would be slower to detect missed blocks.
|
|
|
|
The pragmatic approach might be to only process `BeaconState`s from the canonical
|
|
chain. I don't have a strong preference between approaches.
|
|
```
|
|
|
|
**Guidelines:**
|
|
- Don't be overly prescriptive - present options
|
|
- Mention relevant constraints
|
|
- It's okay to say "I don't have a strong preference"
|
|
|
|
### Optional Sections
|
|
|
|
- `## Additional Info` - Edge cases, related issues
|
|
- `## Metrics` - Performance data, observations
|
|
- `## Version` - For bug reports
|
|
|
|
## Code References
|
|
|
|
**Use GitHub permalinks with commit hashes** so code renders properly:
|
|
|
|
```
|
|
https://github.com/sigp/lighthouse/blob/261322c3e3ee/beacon_node/beacon_processor/src/lib.rs#L809
|
|
```
|
|
|
|
Get commit hash: `git rev-parse unstable`
|
|
|
|
For line ranges: `#L809-L825`
|
|
|
|
## Writing Style
|
|
|
|
### Be Natural and Concise
|
|
- Direct and objective
|
|
- Precise technical terminology
|
|
- Avoid AI-sounding language
|
|
|
|
### Be Honest About Uncertainty
|
|
- Don't guess - ask questions
|
|
- Use tentative language when appropriate ("might", "I think")
|
|
- Present multiple options without picking one
|
|
|
|
### Think About Trade-offs
|
|
- Present multiple approaches
|
|
- Discuss pros and cons
|
|
- Consider backward compatibility
|
|
- Note performance implications
|
|
|
|
## Labels
|
|
|
|
**Type:** `bug`, `enhancement`, `optimization`, `code-quality`, `security`, `RFC`
|
|
|
|
**Component:** `database`, `HTTP-API`, `fork-choice`, `beacon-processor`, etc.
|
|
|
|
**Effort:** `good first issue`, `low-hanging-fruit`, `major-task`
|
|
|
|
## Pull Request Guidelines
|
|
|
|
```markdown
|
|
## Description
|
|
|
|
[What does this PR do? Why is it needed? Be concise and technical.]
|
|
|
|
Closes #[issue-number]
|
|
|
|
## Additional Info
|
|
|
|
[Breaking changes, performance impacts, migration steps, etc.]
|
|
```
|
|
|
|
### Commit Messages
|
|
|
|
Format:
|
|
- First line: Brief summary (imperative mood)
|
|
- Blank line
|
|
- Additional details if needed
|
|
|
|
```
|
|
Add custody info API for data columns
|
|
|
|
Implements `/lighthouse/custody/info` endpoint that returns custody group
|
|
count, custodied columns, and earliest available data column slot.
|
|
```
|
|
|
|
## Anti-Patterns
|
|
|
|
- Vague descriptions without details
|
|
- No code references when describing code
|
|
- Premature solutions without understanding the problem
|
|
- Making claims without validating against codebase
|
|
|
|
## Good Examples
|
|
|
|
- https://github.com/sigp/lighthouse/issues/6120
|
|
- https://github.com/sigp/lighthouse/issues/4388
|
|
- https://github.com/sigp/lighthouse/issues/8216
|