diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..d26383ce9 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,115 @@ +# Copilot Instructions for NVSentinel + +This file provides repository-level instructions for GitHub Copilot to improve +code reviews and suggestions. + +## Project Overview + +NVSentinel is the NVIDIA Device API — a Protocol Buffer and gRPC-based API for +GPU device management. The codebase consists primarily of `.proto` definitions +and their generated Go code. + +## Repository Structure + +``` +api/ +├── proto/ # Protocol Buffer source definitions (edit these) +│ └── device/v1alpha1/ +│ └── gpu.proto +├── gen/go/ # Generated Go code (DO NOT edit manually) +│ └── device/v1alpha1/ +│ ├── gpu.pb.go +│ └── gpu_grpc.pb.go +├── go.mod +└── Makefile +``` + +## Code Review Guidelines + +### Protocol Buffers + +When reviewing `.proto` files: + +- **Field naming**: Use `snake_case` for field names +- **Message/Service naming**: Use `CamelCase` +- **Documentation**: Every message, field, and RPC must have documentation + comments explaining purpose and usage +- **Field numbers**: Never reuse or change field numbers in existing messages +- **Backwards compatibility**: New fields should be optional; avoid breaking + changes to existing APIs +- **Style**: Follow [Google's Protocol Buffer Style Guide](https://protobuf.dev/programming-guides/style/) + +### Generated Code + +- Files in `api/gen/` are **auto-generated** — do not suggest edits to these +- If generated code appears outdated, suggest running `make protos-generate` + +### Go Code + +- Use `gofmt` formatting (enforced by golangci-lint) +- Documentation comments should wrap at 80 characters +- Follow standard Go idioms and error handling patterns +- No manual edits to `*.pb.go` or `*_grpc.pb.go` files + +## Commit Standards + +### Conventional Commits + +All commits must follow conventional commit format: + +``` +feat: add new GPU condition type +fix: correct timestamp handling in conditions +docs: update API documentation +chore: update protoc-gen-go version +``` + +### DCO Sign-off + +All commits **must** include a DCO sign-off line: + +``` +Signed-off-by: Name +``` + +Use `git commit -s` to add this automatically. + +## License Headers + +All source files must include the Apache 2.0 license header: + +``` +Copyright (c) 2026, NVIDIA CORPORATION. All rights reserved. + +Licensed under the Apache License, Version 2.0 (the "License"); +... +``` + +## What to Flag in Reviews + +1. **Breaking API changes** without migration path +2. **Missing documentation** on proto messages/fields/RPCs +3. **Manual edits** to generated files +4. **Missing license headers** +5. **Unsigned commits** (missing DCO) +6. **Non-conventional commit messages** + +## What NOT to Flag + +1. Style issues in generated `*.pb.go` files +2. Import ordering in generated code +3. Line length in generated code + +## Build Commands + +```bash +make protos-generate # Regenerate Go code from .proto files +make build # Build the Go module +make lint # Run go vet +make test # Run tests +``` + +## Tool Versions + +Tool versions are centralized in `.versions.yaml`. When suggesting dependency +updates, reference this file. diff --git a/.github/workflows/device-api-ci.yml b/.github/workflows/device-api-ci.yml new file mode 100644 index 000000000..4565db30c --- /dev/null +++ b/.github/workflows/device-api-ci.yml @@ -0,0 +1,77 @@ +# Copyright (c) 2026, NVIDIA CORPORATION. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +name: Device API CI + +on: + push: + branches: + - device-api + pull_request: + branches: + - device-api + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + lint-test: + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version-file: api/go.mod + cache-dependency-path: api/go.sum + + - name: Install yq + run: | + sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 + sudo chmod +x /usr/local/bin/yq + + - name: Install protoc + run: | + PROTOC_VERSION=$(yq eval '.protobuf.protobuf' .versions.yaml | sed 's/v//') + curl -LO https://github.com/protocolbuffers/protobuf/releases/download/v${PROTOC_VERSION}/protoc-${PROTOC_VERSION}-linux-x86_64.zip + sudo unzip -o protoc-${PROTOC_VERSION}-linux-x86_64.zip -d /usr/local + rm protoc-${PROTOC_VERSION}-linux-x86_64.zip + + - name: Generate protobuf code + run: make -C api protos-generate + + - name: Verify no changes + run: | + if [ -n "$(git status --porcelain)" ]; then + echo "Generated code is out of date. Please run 'make protos-generate' and commit the changes." + git diff + exit 1 + fi + + - name: Run go vet + run: cd api && go vet ./... + + - name: Build + run: make -C api build + + - name: Run tests + run: cd api && go test -v ./...