Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
120 lines (87 loc) · 4.94 KB

CONTRIBUTING.md

File metadata and controls

120 lines (87 loc) · 4.94 KB

Contributing Guide

Thanks for improving HPC-AI-Optimization-Lab.

This repository is in a finishing-and-hardening phase. The goal is not to expand scope aggressively; it is to leave the project clean, credible, and easy to understand. Contributions should reduce drift, clarify intent, and keep the repository maintainable.

Source of truth

Topic Canonical location
Public overview README.md, README.zh-CN.md
User-facing docs and Pages content docs/
Canonical requirements openspec/specs/
Active change scope openspec/changes/<change>/
Human workflow CONTRIBUTING.md
Shared AI workflow AGENTS.md
Tool-specific AI guidance CLAUDE.md, .github/copilot-instructions.md
Release summary CHANGELOG.md
Detailed release notes changelog/

If a lower-value file duplicates one of these sources, prefer the canonical source and remove or rewrite the duplicate.

Contribution workflow

Non-trivial work uses OpenSpec.

  1. Investigate with /opsx:explore when requirements or tradeoffs are unclear.
  2. Create a bounded change with /opsx:propose.
  3. Refine proposal, specs, design, and tasks until the change is apply-ready.
  4. Implement with /opsx:apply or equivalent task-by-task execution.
  5. Run /review before merge.
  6. Archive the completed change with /opsx:archive.

Scope discipline

  • Prefer small serial changes over long-lived parallel branches.
  • Prefer one long autopilot session over /fleet unless the work is genuinely parallel and worth the extra cost.
  • Keep cleanup changes aggressive but safe: delete low-value drift only after a stronger canonical replacement exists.

Repository layout

hpc-ai-optimization-lab/
├── src/          CUDA/C++ implementation
├── tests/        automated tests
├── examples/     runnable examples
├── python/       nanobind bindings and Python-side code
├── docs/         user-facing docs and Pages content
├── openspec/     canonical specs, active changes, archives
├── changelog/    detailed release notes and historical notes
└── .github/      GitHub workflows and templates

Keep the repository root high-signal. Root files should usually be project identity, governance, or build-entry files rather than temporary summaries.

Local development baseline

Use the CMake presets before inventing local variants:

cmake --preset default
cmake --build --preset default
ctest --preset default

If the current build tree is stale or incomplete, reconfigure first. Do not treat a zero-test build tree as authoritative.

Tooling

LSP and editor setup

  • Primary C++/CUDA language server: clangd
  • Primary input for clangd: compile_commands.json generated by CMake
  • Optional CMake editor support is fine if it reduces friction, but keep the baseline tool-agnostic
  • Python-specific editor tooling is only necessary when touching bindings or benchmark code

Hooks

Install hooks with:

pip install pre-commit
pre-commit install

The hook set is intentionally narrow. If a hook does not protect a recurring repository-specific failure mode, remove or simplify it rather than adding more automation.

GitHub operations

Use gh for repository metadata, workflow inspection, and issue/PR operations. Keep GitHub-facing changes scoped and deliberate.

Copilot CLI, LSP, MCP, and plugins

  • Repository-level Copilot instructions live at .github/copilot-instructions.md.
  • Repository-level LSP configuration lives at .github/lsp.json.
  • The default LSP path for this project is clangd backed by compile_commands.json.
  • .clangd points clangd at build/default, so cmake --preset default is the expected first setup step.
  • If you previously built into a legacy top-level build/ tree, rerun cmake --preset default so build/default/compile_commands.json becomes the active compilation database for clangd.
  • Use /lsp to inspect or enable the configured repo-level language server profile in Copilot CLI.
  • Use /remote only to continue the same bounded workflow from GitHub/web surfaces; do not use it to create parallel drift.
  • Use /research for genuinely external or fast-moving information, not for questions answerable from the local repo.
  • Use /mcp and /plugin sparingly. Prefer built-in skills, local files, and gh unless an additional integration provides repeated concrete value for this repository.

Review checklist

Before merging:

  • the change is backed by an OpenSpec change when the scope is non-trivial
  • docs and governance files point to the same source of truth
  • validation commands and limitations are stated honestly
  • unnecessary duplication is removed rather than preserved
  • /review has been run for meaningful changes

What not to add casually

  • long-lived feature branches
  • broad plugin bundles
  • heavy MCP integrations
  • generic assistant boilerplate
  • extra docs that merely repeat README, specs, or existing guidance