mirror of
https://github.com/sigp/lighthouse.git
synced 2026-04-17 21:08:32 +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)
3.3 KiB
3.3 KiB
GitHub Issue & PR Guidelines
Guidelines for creating well-structured GitHub issues and PRs for Lighthouse.
Issue Structure
Start with Description
Always begin with ## Description:
## 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)
## 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
## 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