GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
a3acef32dec8d8ac8051793df3686007a92266cd

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/contributing

docs/contributing/instructions.md

671lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: 'Contributing Instructions to HVE Core'
3description: 'Requirements and standards for contributing GitHub Copilot instruction files to hve-core'
4sidebar_position: 3
5author: Microsoft
6ms.date: 2026-03-17
7ms.topic: how-to
8---
9
10This guide defines the requirements, standards, and best practices for contributing GitHub Copilot instruction files (`.instructions.md`) to the hve-core library.
11
12⚙️ Common Standards: See [AI Artifacts Common Standards](ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).
13
14## What is an Instructions File?
15
16An **instructions file** is a technology-specific or pattern-specific guidance document that defines coding standards, conventions, and best practices for GitHub Copilot to follow when working with particular file types, languages, or frameworks.
17
18## Use Cases for Instructions Files
19
20Create an instructions file when you need to:
21
22* Define language-specific coding standards (e.g., Python, C#, Bash)
23* Establish framework-specific conventions (e.g., Terraform, Bicep)
24* Document file type requirements (e.g., Markdown, YAML)
25* Specify workflow patterns (e.g., commit messages, PR creation)
26* Codify project-specific style guidelines
27* Auto-apply rules based on file patterns (`applyTo` glob matching)
28
29## File Structure Requirements
30
31### Location
32
33Instruction files are typically organized in a collection subdirectory by convention:
34
35```text
36.github/instructions/
37├── {collection-id}/
38│ └── your-instructions.instructions.md # Collection-scoped
39├── coding-standards/
40│ ├── language.instructions.md # Language-specific
41│ └── {language}/
42│ └── language.instructions.md # Language with subdirectory
43├── shared/
44│ └── cross-collection.instructions.md # Shared across collections
45└── hve-core/
46 └── markdown.instructions.md # Collection-scoped (distributed)
47```
48
49> [!IMPORTANT]
50> Files placed directly at the root of `.github/instructions/` (without a subdirectory) are repo-specific and never distributed through extension packages or collections. Only use root-level placement for internal repository concerns such as CI/CD workflows or conventions that do not generalize to consumers. Files in subdirectories like `hve-core/`, `ado/`, and `shared/` are collection-scoped and distributable.
51
52<!-- markdownlint-disable-next-line MD028 -->
53
54> [!NOTE]
55> Collections can reference artifacts from any subfolder. The `path:` field in collection YAML files
56> accepts any valid repo-relative path regardless of the artifact's parent directory.
57
58#### Examples
59
60* `.github/instructions/coding-standards/python-script.instructions.md`
61* `.github/instructions/hve-core/markdown.instructions.md`
62* `.github/instructions/coding-standards/csharp/csharp.instructions.md`
63* `.github/instructions/coding-standards/bash/bash.instructions.md`
64
65### Naming Convention
66
67* Use lowercase kebab-case: `python-script.instructions.md`
68* Be specific about target: `csharp-tests.instructions.md`
69* Include domain prefix when needed: `ado-wit-planning.instructions.md`
70* Avoid generic names: `code.instructions.md` ❌ → `python-script.instructions.md` ✅
71
72### File Format
73
74Instruction files MUST:
75
761. Use the `.instructions.md` extension
772. Start with valid YAML frontmatter between `---` delimiters
783. End with single newline character
79
80## Frontmatter Requirements
81
82### Required Fields
83
84**`description`** (string, MANDATORY)
85
86| Property | Value |
87|----------|-------------------------------------------------------------------------------------------|
88| Purpose | Concise explanation of instruction scope and target |
89| Format | Single sentence, 10-200 characters |
90| Style | Sentence case with proper punctuation |
91| Example | `'Required instructions for Python script implementation with type hints and docstrings'` |
92
93**`applyTo`** (string, MANDATORY for auto-applied instructions)
94
95| Property | Value |
96|----------|-----------------------------------------------------------|
97| Purpose | Glob pattern(s) defining when these instructions activate |
98| Format | Valid glob pattern or comma-separated patterns |
99| Scope | Matches from repository root |
100
101Examples:
102
103* Single pattern: `**/*.py`
104* Multiple files: `**/*.py, **/*.ipynb`
105* Directory scope: `**/src/**/*.sh`
106* Specific paths: `**/.copilot-tracking/pr/new/**`
107
108### Optional Fields
109
110**`version`** (string)
111
112| Property | Value |
113|----------|---------------------------------------------------------|
114| Purpose | Tracks instruction file revisions |
115| Format | Semantic versioning (e.g., `1.0.0`) |
116| Pattern | `^\d+\.\d+(\.\d+)?$` (major.minor or major.minor.patch) |
117
118**`author`** (string)
119
120Attribution for the instruction creator (e.g., `microsoft/hve-core`, `your-team-name`).
121
122**`lastUpdated`** (string)
123
124Timestamp of last modification in ISO 8601 format (YYYY-MM-DD).
125
126### Frontmatter Example
127
128```yaml
129---
130description: 'Required instructions for Python script implementation with type hints, docstrings, and error handling'
131applyTo: '**/*.py, **/*.ipynb'
132version: '1.0.0'
133author: 'microsoft/hve-core'
134lastUpdated: '2025-11-19'
135---
136```
137
138## Collection Entry Requirements
139
140All instructions must have matching entries in one or more `collections/*.collection.yml` manifests, except for repo-specific instructions placed at the root of `.github/instructions/` (without a subdirectory). Collection entries control distribution and maturity.
141
142> [!NOTE]
143> Root-level instructions (directly under `.github/instructions/` with no subdirectory) are repo-specific and MUST NOT be added to collection manifests. See [Repo-Specific Artifact Exclusion](ai-artifacts-common.md#repo-specific-artifact-exclusion) for details.
144
145### Adding Your Instructions to a Collection
146
147After creating your instructions file, add an `items[]` entry in each target collection manifest:
148
149```yaml
150items:
151 # path can reference artifacts from any subfolder
152 - path: .github/instructions/{collection-id}/my-language.instructions.md
153 kind: instruction
154 maturity: stable
155```
156
157For instructions in language subdirectories, use the full path:
158
159```yaml
160items:
161 - path: .github/instructions/coding-standards/csharp/csharp.instructions.md
162 kind: instruction
163 maturity: stable
164```
165
166### Selecting Collections for Instructions
167
168Choose collections based on who uses the technology or pattern:
169
170| Instruction Type | Recommended Collections |
171|-------------------------|---------------------------------------------------|
172| Language standards | `hve-core-all`, `coding-standards` |
173| Infrastructure (IaC) | `hve-core-all`, `coding-standards` |
174| Documentation standards | `hve-core-all`, `hve-core` |
175| Workflow instructions | `hve-core-all` plus relevant workflow collections |
176| Test standards | `hve-core-all`, `coding-standards` |
177| ADO integration | `hve-core-all`, `ado`, `project-planning` |
178
179For complete collection documentation, see [AI Artifacts Common Standards - Collection Manifests](ai-artifacts-common.md#collection-manifests-and-dependencies).
180
181## Content Structure Standards
182
183### Required Sections
184
185#### 1. Title (H1)
186
187* Clear heading describing target technology/pattern
188* Should align with filename and scope
189
190```markdown
191# Python Script Implementation Instructions
192```
193
194#### 2. Overview/Scope
195
196* Explains what these instructions cover
197* Defines when they apply
198* Lists any prerequisites or assumptions
199
200```markdown
201## Scope
202
203These instructions apply to all Python scripts in the repository, covering:
204
205* Code structure and organization
206* Type hinting and documentation
207* Error handling patterns
208* Testing requirements
209```
210
211#### 3. Core Standards/Conventions
212
213* Defines mandatory coding patterns
214* Uses RFC 2119 keywords (MUST, SHOULD, MAY)
215* Organizes by category (structure, naming, patterns)
216* Provides rationale for key decisions
217
218```markdown
219## Code Structure
220
221Scripts MUST follow this organization:
222
2231. Shebang (if executable)
2242. Module docstring
2253. Imports (standard library → third-party → local)
2264. Constants
2275. Functions/classes
2286. Main execution block
229```
230
231#### 4. Naming Conventions
232
233* Specifies naming patterns for identifiers
234* Covers files, functions, classes, variables, constants
235* Provides examples of correct usage
236
237```markdown
238## Naming Conventions
239
240* Files: `snake_case.py` (e.g., `data_processor.py`)
241* Functions: `snake_case()` (e.g., `process_data()`)
242* Classes: `PascalCase` (e.g., `DataProcessor`)
243* Constants: `SCREAMING_SNAKE_CASE` (e.g., `MAX_RETRIES`)
244* Private: `_leading_underscore` (e.g., `_internal_helper()`)
245```
246
247#### 5. Code Examples
248
249* Demonstrates correct patterns with working code
250* Shows both positive (✅) and negative (❌) examples
251* Wraps in XML-style blocks for reusability
252* Includes inline comments explaining key points
253
254````markdown
255<!-- <example-python-function> -->
256```python
257def calculate_average(numbers: list[float]) -> float:
258 """
259 Calculate the arithmetic mean of a list of numbers.
260
261 Args:
262 numbers: List of numeric values to average
263
264 Returns:
265 Arithmetic mean of the input numbers
266
267 Raises:
268 ValueError: If the input list is empty
269 """
270 if not numbers:
271 raise ValueError("Cannot calculate average of empty list")
272
273 return sum(numbers) / len(numbers)
274```
275<!-- </example-python-function> -->
276````
277
278#### 6. Anti-Patterns
279
280* Documents what to avoid
281* Explains why patterns are problematic
282* Shows correct alternatives
283
284```markdown
285## Anti-Patterns
286
287❌ Bare except clauses:
288```python
289try:
290 risky_operation()
291except: # DON'T DO THIS
292 pass
293```
294
295✅ Specific exception handling:
296
297```python
298try:
299 risky_operation()
300except FileNotFoundError as e:
301 logger.error(f"File not found: {e}")
302 raise
303```
304
305#### 7. Validation/Testing
306
307* Specifies validation tools and commands
308* Defines testing requirements
309* Lists quality gates
310
311```markdown
312## Validation
313
314All Python code MUST pass:
315
316* Linting: `ruff check .`
317* Type checking: `mypy --strict .`
318* Testing: `pytest tests/ --cov=src`
319* Coverage: Minimum 80% line coverage
320```
321
322#### 8. Attribution Footer
323
324Always include an attribution footer at the end of the file.
325
326```markdown
327---
328
329Brought to you by microsoft/hve-core
330```
331
332### XML-Style Block Requirements
333
334See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules. Common tags for instructions:
335
336* `<!-- <example-{pattern-name}> -->` - Code examples
337* `<!-- <convention-{category}> -->` - Convention blocks
338* `<!-- <anti-pattern-{issue}> -->` - Things to avoid
339* `<!-- <validation-checklist> -->` - Validation steps
340* `<!-- <file-structure> -->` - File organization
341
342### Directive Language Standards
343
344Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See [AI Artifacts Common Standards - RFC 2119 Directive Language](ai-artifacts-common.md#rfc-2119-directive-language) for complete guidance.
345
346## Pattern Definition Standards
347
348Instructions should clearly define:
349
350### File Organization
351
352Structure for target files:
353
354````markdown
355<!-- <file-structure-python-script> -->
356```python
357#!/usr/bin/env python3
358"""
359Module-level docstring describing purpose and usage.
360"""
361
362# Standard library imports
363import os
364import sys
365from pathlib import Path
366
367# Third-party imports
368import requests
369import pandas as pd
370
371# Local imports
372from .utils import helper_function
373
374# Constants
375MAX_RETRIES = 3
376DEFAULT_TIMEOUT = 30
377
378# Functions and classes
379def main() -> int:
380 """Main entry point."""
381 return 0
382
383# Main execution
384if __name__ == "__main__":
385 sys.exit(main())
386```
387<!-- </file-structure-python-script> -->
388````
389
390### Code Patterns
391
392Approved implementation patterns:
393
394````markdown
395## Error Handling Pattern
396
397<!-- <pattern-error-handling> -->
398```python
399def process_file(file_path: Path) -> dict[str, Any]:
400 """
401 Process a configuration file with proper error handling.
402
403 Args:
404 file_path: Path to configuration file
405
406 Returns:
407 Parsed configuration dictionary
408
409 Raises:
410 FileNotFoundError: If configuration file doesn't exist
411 ValueError: If configuration is invalid
412 """
413 if not file_path.exists():
414 raise FileNotFoundError(f"Configuration not found: {file_path}")
415
416 try:
417 with file_path.open() as f:
418 config = json.load(f)
419 except json.JSONDecodeError as e:
420 raise ValueError(f"Invalid JSON in {file_path}: {e}")
421
422 # Validate required keys
423 required = {"version", "settings"}
424 if not required.issubset(config.keys()):
425 missing = required - config.keys()
426 raise ValueError(f"Missing required keys: {missing}")
427
428 return config
429```
430<!-- </pattern-error-handling> -->
431````
432
433### Style Conventions
434
435Formatting and style rules:
436
437```markdown
438## Style Conventions
439
440* Indentation: 4 spaces (no tabs)
441* Line length: 88 characters (Black formatter default)
442* Quotes: Double quotes for strings, single for dict keys
443* Imports: Organized by isort with Black-compatible settings
444* Trailing commas: Use in multi-line collections
445* Type hints: Use modern syntax (`list[str]` not `List[str]`)
446```
447
448## Validation and Tooling
449
450### Linting Configuration
451
452Specify tools and configurations:
453
454````markdown
455## Linting
456
457All Python code MUST pass Ruff checks:
458
459<!-- <config-ruff> -->
460```toml
461[tool.ruff]
462line-length = 88
463target-version = "py311"
464
465[tool.ruff.lint]
466select = ["E", "F", "I", "N", "W", "UP"]
467ignore = ["E501"] # Line too long (handled by formatter)
468```
469<!-- </config-ruff> -->
470
471Run: `ruff check . --fix`
472````
473
474### Testing Requirements
475
476Define test expectations:
477
478```markdown
479## Testing Requirements
480
481* Coverage: Minimum 80% line coverage
482* Test location: `tests/` directory mirroring `src/` structure
483* Test naming: `test_*.py` files, `test_*` functions
484* Fixtures: Use pytest fixtures for shared test data
485* Mocking: Mock external dependencies (file I/O, network calls)
486
487<!-- <example-pytest-test> -->
488```python
489import pytest
490from pathlib import Path
491from mymodule import process_file
492
493def test_process_file_valid(tmp_path: Path) -> None:
494 """Test processing valid configuration file."""
495 config_file = tmp_path / "config.json"
496 config_file.write_text('{"version": "1.0", "settings": {}}')
497
498 result = process_file(config_file)
499
500 assert result["version"] == "1.0"
501 assert "settings" in result
502
503def test_process_file_missing(tmp_path: Path) -> None:
504 """Test handling of missing configuration file."""
505 config_file = tmp_path / "missing.json"
506
507 with pytest.raises(FileNotFoundError):
508 process_file(config_file)
509```
510<!-- </example-pytest-test> -->
511
512## Glob Pattern Guidelines
513
514The `applyTo` field uses glob patterns to match files:
515
516### Pattern Syntax
517
518* `*` - Matches any characters except `/`
519* `**` - Matches any characters including `/` (recursive)
520* `?` - Matches single character
521* `[abc]` - Matches any character in brackets
522* `{a,b}` - Matches either `a` or `b`
523
524### Common Patterns
525
526```yaml
527# Single file extension
528applyTo: '**/*.py'
529
530# Multiple extensions
531applyTo: '**/*.py, **/*.ipynb'
532
533# Specific directory
534applyTo: '**/src/**/*.ts'
535
536# Specific path pattern
537applyTo: '**/.copilot-tracking/plans/*.md'
538
539# Exclude pattern (handled by negative patterns in schema-mapping.json)
540# Not directly in applyTo, but can be configured
541```
542
543### Testing Patterns
544
545Verify your glob pattern matches intended files:
546
547```bash
548# PowerShell
549Get-ChildItem -Path . -Recurse -Include *.py
550
551# Bash
552find . -name "*.py"
553```
554
555## Validation Checklist
556
557Before submitting your instructions file, verify:
558
559### File Format Structure
560
561* [ ] File uses `.instructions.md` extension
562* [ ] File starts with YAML frontmatter between `---` delimiters
563* [ ] File ends with single newline character (EOF)
564* [ ] No trailing whitespace on any lines
565* [ ] Uses UTF-8 encoding
566
567### Frontmatter
568
569* [ ] Valid YAML between `---` delimiters
570* [ ] `description` field present and descriptive (10-200 chars)
571* [ ] `applyTo` field with valid glob pattern (if auto-applied)
572* [ ] `version` follows semantic versioning format (if present)
573* [ ] No trailing whitespace in values
574
575### Content Structure
576
577* [ ] Clear H1 title describing target
578* [ ] Overview/scope section
579* [ ] Core standards with RFC 2119 keywords
580* [ ] Naming conventions documented
581* [ ] Code examples wrapped in XML-style blocks
582* [ ] Anti-patterns section with alternatives
583* [ ] Validation/testing requirements
584* [ ] Attribution footer present
585
586### Code Examples
587
588* [ ] All examples are syntactically correct
589* [ ] Examples include necessary imports/context
590* [ ] Both positive and negative examples provided
591* [ ] Examples wrapped in XML-style blocks with unique names
592* [ ] Code blocks have language tags
593* [ ] Inline comments explain key points
594
595### Common Standards
596
597* [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards))
598* [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards))
599* [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language))
600
601### Technical Validation
602
603* [ ] Glob pattern in `applyTo` is valid and tested
604* [ ] All file references point to existing files
605* [ ] External links are valid and accessible
606* [ ] Tool/command references are correct
607* [ ] No conflicts with existing instructions files
608
609### Integration
610
611* [ ] Aligns with `.github/copilot-instructions.md`
612* [ ] Follows repository conventions
613* [ ] Compatible with existing instructions
614* [ ] Does not duplicate existing instruction functionality
615* [ ] Glob pattern doesn't conflict with other instructions
616
617## Testing Your Instructions
618
619See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For instructions specifically:
620
6211. Verify `applyTo` glob pattern matches intended files
6222. Test all code examples execute correctly
6233. Have Copilot generate code following your instructions
6244. Validate specified linting/validation commands work
625
626## Common Issues and Fixes
627
628### Instructions-Specific Issues
629
630### Invalid Glob Pattern
631
632Glob patterns that only match root directory or contain syntax errors cause matching failures. Use the `**/` prefix for recursive matching (e.g., `**/*.py` for all Python files recursively).
633
634### Conflicting Patterns
635
636Multiple instruction files with overlapping glob patterns cause ambiguity. Make patterns more specific (e.g., `**/tests/**/*.py` vs `**/*.py`) or ensure they target distinct file sets.
637
638For additional common issues (XML blocks, markdown, directives), see [AI Artifacts Common Standards - Common Issues and Fixes](ai-artifacts-common.md#common-issues-and-fixes).
639
640## Automated Validation
641
642Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)):
643
644* `npm run lint:frontmatter`
645* `npm run lint:md`
646* `npm run spell-check`
647* `npm run lint:md-links`
648
649All checks **MUST** pass before merge.
650
651## Related Documentation
652
653* [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions
654* [Contributing Custom Agents](custom-agents.md) - AI agent configuration files
655* [Contributing Prompts](prompts.md) - Workflow-specific guidance
656* [Pull Request Template](https://github.com/microsoft/hve-core/blob/main/.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements
657
658## Getting Help
659
660See [AI Artifacts Common Standards - Getting Help](ai-artifacts-common.md#getting-help) for support resources. For instructions-specific assistance:
661
662* Review existing examples in `.github/instructions/{collection-id}/` (the conventional location for instruction files)
663* Test glob patterns using file search commands
664* Use `prompt-builder.agent.md` agent for assistance
665
666---
667
668<!-- markdownlint-disable MD036 -->
669*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
670then carefully refined by our team of discerning human reviewers.*
671<!-- markdownlint-enable MD036 -->
672