GitHub Copilot Instructions: vcpkg-registry maintenance
Introduction
This vcpkg registry provides an overlay of custom ports for the vcpkg package manager. This file defines how GitHub Copilot should assist with repository maintenance tasks.
For repository overview and setup instructions, see README.md.
Core Maintenance Tasks
The primary maintenance tasks for this registry are:
1. Create Port
Goal: Add a new vcpkg port to this registry.
Documentation:
- docs/guide-create-port.md – Main creation guide
- docs/guide-create-port-build.md – Build patterns
- docs/guide-create-port-download.md – Download & SHA512
Prompts:
/search-port – .github/prompts/search-port.prompt.md/create-port – .github/prompts/create-port.prompt.md/install-port – .github/prompts/install-port.prompt.md/review-port – .github/prompts/review-port.prompt.md
2. Update Port
Goal: Update an existing port to a newer version or adjust its build configuration.
Documentation:
- docs/guide-update-port.md – Update procedures
Prompts:
/check-port-upstream – .github/prompts/check-port-upstream.prompt.md/update-port – .github/prompts/update-port.prompt.md/install-port – .github/prompts/install-port.prompt.md/review-port – .github/prompts/review-port.prompt.md
3. Update Version Baseline
Goal: Synchronize versions/ JSON files with changes to ports.
Documentation:
- docs/guide-update-version-baseline.md – Baseline update procedures
Prompts:
/update-version-baseline – .github/prompts/update-version-baseline.prompt.md
4. Troubleshoot Port
Goal: Diagnose and fix issues with port installation or build.
Documentation:
- docs/troubleshooting.md – Common issues and solutions
Prompts:
/check-environment – .github/prompts/check-environment.prompt.md/install-port – .github/prompts/install-port.prompt.md/review-port – .github/prompts/review-port.prompt.md
How Copilot Should Use Documentation
When assisting with tasks:
- For setup and environment: Reference README.md and docs/references.md
- For step-by-step instructions: Use the specific guides in
docs/:
- docs/guide-create-port.md
- docs/guide-update-port.md
- docs/guide-update-version-baseline.md
- docs/troubleshooting.md
- For external resources: Use docs/references.md
- Prompt behavior must follow the corresponding guide's process
How Copilot Should Use Prompts
Task-to-Prompt-to-Guide Mapping
| Task | Prompts | Primary Guides |
|---|
| Create port | /search-port → /create-port → /install-port → /review-port | guide-create-port.md, guide-create-port-build.md, guide-create-port-download.md |
| Update port | /check-port-upstream → /update-port → /install-port → /review-port | guide-update-port.md |
| Update version baseline | /update-version-baseline | guide-update-version-baseline.md |
| Troubleshoot | /check-environment → /install-port | troubleshooting.md |
Prompt Guidelines
- Prompts are for process execution with clear pass/fail outcomes
- Each prompt should report structured results with ✅ ⚠️ ❌ indicators
- Follow the workflow defined in the prompt's corresponding guide
Command Usage Guidelines
Overlay Usage
- Use explicit CLI options (
--overlay-ports, --overlay-triplets) instead of environment variables
- See docs/guide-create-port.md and docs/troubleshooting.md for examples
Helper Scripts
Prefer helper scripts in scripts/ when available:
- registry-add-version.ps1 – Update version baseline
- registry-format.ps1 – Format manifests files in ports folder
Minimal Changes
- Keep changes focused on the requested task
- Avoid unrelated refactoring
- Test only what's relevant to the change
Safety and Scope Constraints
- No automatic commits unless explicitly requested
- Stay within task scope – don't modify unrelated ports or versions
- Run tests/installs only when relevant to the requested change
- Follow vcpkg best practices as documented in guides
Navigation Graphs
Mermaid Diagram
graph TD
README[README.md] --> CreateGuide[docs/guide-create-port.md]
CreateGuide -- prompt --> CreatePrompt[create-port.prompt.md]
CreateGuide --> BuildGuide[docs/guide-create-port-build.md]
CreateGuide --> DownloadGuide[docs/guide-create-port-download.md]
CreateGuide --> Troubleshoot[docs/troubleshooting.md]
UpdateGuide[docs/guide-update-port.md] -- prompt --> UpdatePrompt[update-port.prompt.md]
UpdateGuide --> BaselineGuide[docs/guide-update-version-baseline.md]
BaselineGuide -- prompt --> BaselinePrompt[update-version-baseline.prompt.md]
BaselineGuide --> Troubleshoot
Troubleshoot -- prompt --> InstallPrompt[install-port.prompt.md]
Troubleshoot -- prompt --> CheckEnvPrompt[check-environment.prompt.md]
References[docs/references.md] --> CreateGuide
References --> UpdateGuide