microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
.github/instructions/pull-request.instructions.md
174lines · modecode
| 1 | --- |
| 2 | description: 'Repository-specific pull request conventions for hve-core including template mapping, change detection, and maturity tracking - Brought to you by microsoft/hve-core' |
| 3 | applyTo: '**/.copilot-tracking/pr/**' |
| 4 | --- |
| 5 | |
| 6 | # Pull Request Conventions |
| 7 | |
| 8 | Repository-specific conventions for pull request generation in hve-core. Follow #file:hve-core/pull-request.instructions.md for the pull request generation workflow. |
| 9 | |
| 10 | ## Template Integration |
| 11 | |
| 12 | When a repository template exists, keep unfilled placeholders for manual completion. |
| 13 | |
| 14 | Rich markdown formatting is permitted within all sections, including `###` sub-headings, bold, italics, blockquotes, and prose paragraphs. |
| 15 | |
| 16 | Report that the repository template was used once generation completes. |
| 17 | |
| 18 | ### Manual-Only Sections |
| 19 | |
| 20 | These sections require human verification. The agent does not modify them: |
| 21 | |
| 22 | * AI artifact contribution verification checkboxes (under the checklist section) |
| 23 | * Prompt-builder review attestation checkbox (under type of change) |
| 24 | * Free-form other type checkbox (under type of change) |
| 25 | |
| 26 | ### Section Fill Guidance |
| 27 | |
| 28 | #### Sample Prompts |
| 29 | |
| 30 | When AI artifact changes are detected (`.instructions.md`, `.prompt.md`, `.agent.md`, `SKILL.md`), fill sub-sections from pr-reference-log.md analysis: |
| 31 | |
| 32 | | Sub-section | Content Source | |
| 33 | |--------------------|-------------------------------------------------------------| |
| 34 | | User Request | Describe how to trigger or invoke the modified artifact | |
| 35 | | Execution Flow | Summarize key steps, tool usage, and decision points | |
| 36 | | Output Artifacts | List files or content created with brief previews | |
| 37 | | Success Indicators | Describe how users verify correct operation | |
| 38 | |
| 39 | > [!NOTE] |
| 40 | > Human review is recommended for agent-populated Sample Prompts content. |
| 41 | |
| 42 | Leave the section empty with placeholder comments intact when the PR does not include AI artifact changes. |
| 43 | |
| 44 | #### Testing |
| 45 | |
| 46 | Document all testing performed by the agent: |
| 47 | |
| 48 | * List each automated validation command run in Step 6 and its pass/fail status. |
| 49 | * Summarize security analysis findings. |
| 50 | * Summarize diff-based assessments performed. |
| 51 | * Note that manual testing was not performed when applicable. |
| 52 | |
| 53 | > [!NOTE] |
| 54 | > Add manual testing descriptions when applicable. |
| 55 | |
| 56 | ### Special Insertion Rules |
| 57 | |
| 58 | * Insert a GHCP Maturity section before `## Additional Notes` when non-stable GHCP artifacts are detected. |
| 59 | |
| 60 | ## Checkbox Reference |
| 61 | |
| 62 | Single authoritative reference for all checkbox handling in the PR template. All other sections that mention checkboxes defer to this table. |
| 63 | |
| 64 | > [!NOTE] |
| 65 | > Review this table when the PR template changes to ensure checkbox purposes and template locations remain accurate. |
| 66 | |
| 67 | | Template Location | Checkbox Purpose | Handling | Step | Rule Summary | |
| 68 | |---|---|---|---|---| |
| 69 | | Type of Change | Auto-detected change type categories | Agent (auto) | Step 5 | Check via Change Type Detection pattern match | |
| 70 | | Type of Change | Prompt-builder review attestation | Manual | N/A | Human verification; never checked by agent | |
| 71 | | Type of Change | Free-form other type | Manual | N/A | Human verification; never checked by agent | |
| 72 | | Security Considerations | Sensitive data attestation | Agent (auto) | Step 5 | Check when customer data and secrets analysis both pass | |
| 73 | | Security Considerations | Dependency security review | Agent (conditional) | Step 5 | Evaluate only when dependency changes exist | |
| 74 | | Security Considerations | Privilege scope attestation | Agent (conditional) | Step 5 | Evaluate only when security scripts are modified | |
| 75 | | Checklist > Required Checks | Documentation update verification | Agent (assessed) | Step 5 | Check when docs/ changes accompany code changes | |
| 76 | | Checklist > Required Checks | Naming convention compliance | Agent (assessed) | Step 5 | Check when changed files follow repository patterns | |
| 77 | | Checklist > Required Checks | Backwards compatibility verification | Agent (assessed) | Step 5 | Check only when diff shows no removal of public API surfaces | |
| 78 | | Checklist > Required Checks | Test coverage verification | Agent (assessed) | Step 5 | Check only when test files are in changes | |
| 79 | | Checklist > AI Artifact Contributions | AI artifact contribution verification | Manual | N/A | Human verification; never checked by agent | |
| 80 | | Checklist > Required Automated Checks | Validation command results | Agent (automated) | Step 6 | Check for each command that passed in Step 6B | |
| 81 | | GHCP Maturity (inserted) | Non-stable artifact acknowledgment | Manual | N/A | Inserted only when non-stable GHCP artifacts detected; left unchecked | |
| 82 | |
| 83 | When a conditional checkbox's trigger condition is not met, annotate the checkbox inline with `(N/A — {brief reason})` to distinguish skipped-as-not-applicable from evaluated-and-failed. |
| 84 | |
| 85 | ## Change Type Detection Patterns |
| 86 | |
| 87 | Analyze changed files from the pr-reference-log.md analysis. This table maps file patterns, branch patterns, and commit patterns to the change type checkboxes in the PR template. |
| 88 | |
| 89 | > [!NOTE] |
| 90 | > Detection pattern values are matched against PR template checkbox labels. Synchronize this table when template checkbox text changes. |
| 91 | |
| 92 | | Change Type | File Pattern | Branch Pattern | Commit Pattern | |
| 93 | |----------------------------|--------------------------|---------------------------|---------------------------| |
| 94 | | Bug fix | N/A | `^(fix\|bugfix\|hotfix)/` | `^fix(\(.+\))?:` | |
| 95 | | New feature | N/A | `^(feat\|feature)/` | `^feat(\(.+\))?:` | |
| 96 | | Breaking change | N/A | N/A | `BREAKING CHANGE:\|^.+!:` | |
| 97 | | Documentation update | `^docs/.*\.md$` | `^docs/` | `^docs(\(.+\))?:` | |
| 98 | | GitHub Actions workflow | `^\.github/workflows/.*` | N/A | `^ci(\(.+\))?:` | |
| 99 | | Linting configuration | `\.markdownlint.*` | N/A | `^lint(\(.+\))?:` | |
| 100 | | Security configuration | `^scripts/security/.*` | N/A | N/A | |
| 101 | | DevContainer configuration | `^\.devcontainer/.*` | N/A | N/A | |
| 102 | | Dependency update | `package.*\.json` | `^deps/` | `^deps(\(.+\))?:` | |
| 103 | | Copilot instructions | `.*\.instructions\.md$` | N/A | N/A | |
| 104 | | Copilot prompt | `.*\.prompt\.md$` | N/A | N/A | |
| 105 | | Copilot agent | `.*\.agent\.md$` | N/A | N/A | |
| 106 | | Copilot skill | `.*/SKILL\.md$` | N/A | N/A | |
| 107 | | Script or automation | `.*\.(ps1\|sh\|py)$` | N/A | N/A | |
| 108 | |
| 109 | Priority rules: |
| 110 | |
| 111 | * AI artifact patterns (`.instructions.md`, `.prompt.md`, `.agent.md`, `SKILL.md`) take precedence over documentation updates. |
| 112 | * Any breaking change in commits marks the PR as breaking. |
| 113 | * Multiple change types can be selected. |
| 114 | * When changed files do not match any detection pattern, leave "Other" unchecked for manual completion. |
| 115 | |
| 116 | ## GHCP Maturity Detection |
| 117 | |
| 118 | Skip this section when no GHCP artifact files (`.instructions.md`, `.prompt.md`, `.agent.md`, `SKILL.md`) are included in the changes. |
| 119 | |
| 120 | After detecting GHCP files from change type detection, look up maturity levels from collection manifest item metadata: |
| 121 | |
| 122 | 1. For each file matching `.instructions.md`, `.prompt.md`, `.agent.md`, or `SKILL.md` patterns, find matching entries in `collections/*.collection.yml`. |
| 123 | 2. Read each item's optional `maturity` field; use `stable` when omitted. |
| 124 | 3. When the same file appears in multiple collections, use the highest-risk effective value in this order: `deprecated`, `experimental`, `preview`, `stable`. |
| 125 | |
| 126 | Categorize files by maturity: |
| 127 | |
| 128 | | Maturity Level | Risk Level | Indicator | Action | |
| 129 | |----------------|-------------|---------------------------|---------------------------------| |
| 130 | | stable | ✅ Low | Production-ready | Include in standard change list | |
| 131 | | preview | 🔶 Medium | Pre-release feature | Flag in dedicated section | |
| 132 | | experimental | ⚠️ High | May have breaking changes | Add warning banner | |
| 133 | | deprecated | 🚫 Critical | Scheduled for removal | Add deprecation notice | |
| 134 | |
| 135 | ## GHCP Maturity Output |
| 136 | |
| 137 | If non-stable GHCP files are detected, add this section before Notes. |
| 138 | |
| 139 | For experimental files: |
| 140 | |
| 141 | ```markdown |
| 142 | > [!WARNING] |
| 143 | > This PR includes **experimental** GHCP artifacts that may have breaking changes. |
| 144 | > - `path/to/file.prompt.md` |
| 145 | ``` |
| 146 | |
| 147 | For deprecated files: |
| 148 | |
| 149 | ```markdown |
| 150 | > [!CAUTION] |
| 151 | > This PR includes **deprecated** GHCP artifacts scheduled for removal. |
| 152 | > - `path/to/legacy.agent.md` |
| 153 | ``` |
| 154 | |
| 155 | Always include the maturity summary table when any GHCP files are detected: |
| 156 | |
| 157 | ```markdown |
| 158 | ## GHCP Artifact Maturity |
| 159 | |
| 160 | | File | Type | Maturity | Notes | |
| 161 | |--------------------------|--------------|-----------------|------------------| |
| 162 | | `new-feature.prompt.md` | Prompt | ⚠️ experimental | Pre-release only | |
| 163 | | `helper.agent.md` | Agent | 🔶 preview | Pre-release only | |
| 164 | | `video-to-gif/SKILL.md` | Skill | ✅ stable | All builds | |
| 165 | | `coding.instructions.md` | Instructions | ✅ stable | All builds | |
| 166 | ``` |
| 167 | |
| 168 | If any non-stable files detected, add: |
| 169 | |
| 170 | ```markdown |
| 171 | ### GHCP Maturity Acknowledgment |
| 172 | - [ ] I acknowledge this PR includes non-stable GHCP artifacts |
| 173 | - [ ] Non-stable artifacts are intentional for this change |
| 174 | ``` |