microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

hve-core-v3.3.27

Find a branch or tag

Branches

hve-core-v3.3.27

Clone

HTTPS

Download ZIP

hve-core/docs/contributing

docs/contributing/instructions.md

671lines · modecode

Raw Download

chore(docs): correct New-MsDateReport table rendering and refresh stale docs (#1114)c2b806f

2 months ago

1	`---`
2	`title: 'Contributing Instructions to HVE Core'`
3	`description: 'Requirements and standards for contributing GitHub Copilot instruction files to hve-core'`
4	`sidebar_position: 3`
5	`author: Microsoft`
6	`ms.date: 2026-03-17`
7	`ms.topic: how-to`
8	`---`
9
10	This 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
16	`An 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
20	`Create 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
33	`Instruction 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
74	`Instruction files MUST:`
75
76	1. Use the `.instructions.md` extension
77	2. Start with valid YAML frontmatter between `---` delimiters
78	`3. 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
101	`Examples:`
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
120	Attribution for the instruction creator (e.g., `microsoft/hve-core`, `your-team-name`).
121
122	`lastUpdated` (string)
123
124	`Timestamp of last modification in ISO 8601 format (YYYY-MM-DD).`
125
126	`### Frontmatter Example`
127
128	```yaml
129	`---`
130	`description: 'Required instructions for Python script implementation with type hints, docstrings, and error handling'`
131	`applyTo: '*/.py, */.ipynb'`
132	`version: '1.0.0'`
133	`author: 'microsoft/hve-core'`
134	`lastUpdated: '2025-11-19'`
135	`---`
136	```
137
138	`## Collection Entry Requirements`
139
140	All 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
147	After creating your instructions file, add an `items[]` entry in each target collection manifest:
148
149	```yaml
150	`items:`
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
157	`For instructions in language subdirectories, use the full path:`
158
159	```yaml
160	`items:`
161	`- path: .github/instructions/coding-standards/csharp/csharp.instructions.md`
162	`kind: instruction`
163	`maturity: stable`
164	```
165
166	`### Selecting Collections for Instructions`
167
168	`Choose 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
179	`For 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
203	`These 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
221	`Scripts MUST follow this organization:`
222
223	`1. Shebang (if executable)`
224	`2. Module docstring`
225	`3. Imports (standard library → third-party → local)`
226	`4. Constants`
227	`5. Functions/classes`
228	`6. 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
257	`def 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
289	`try:`
290	`risky_operation()`
291	`except: # DON'T DO THIS`
292	`pass`
293	```
294
295	`✅ Specific exception handling:`
296
297	```python
298	`try:`
299	`risky_operation()`
300	`except 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
314	`All 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
324	`Always include an attribution footer at the end of the file.`
325
326	```markdown
327	`---`
328
329	`Brought to you by microsoft/hve-core`
330	```
331
332	`### XML-Style Block Requirements`
333
334	`See [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
344	`Use 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
348	`Instructions should clearly define:`
349
350	`### File Organization`
351
352	`Structure for target files:`
353
354	````markdown
355	`<!-- <file-structure-python-script> -->`
356	```python
357	`#!/usr/bin/env python3`
358	`"""`
359	`Module-level docstring describing purpose and usage.`
360	`"""`
361
362	`# Standard library imports`
363	`import os`
364	`import sys`
365	`from pathlib import Path`
366
367	`# Third-party imports`
368	`import requests`
369	`import pandas as pd`
370
371	`# Local imports`
372	`from .utils import helper_function`
373
374	`# Constants`
375	`MAX_RETRIES = 3`
376	`DEFAULT_TIMEOUT = 30`
377
378	`# Functions and classes`
379	`def main() -> int:`
380	`"""Main entry point."""`
381	`return 0`
382
383	`# Main execution`
384	`if __name__ == "__main__":`
385	`sys.exit(main())`
386	```
387	`<!-- </file-structure-python-script> -->`
388	````
389
390	`### Code Patterns`
391
392	`Approved implementation patterns:`
393
394	````markdown
395	`## Error Handling Pattern`
396
397	`<!-- <pattern-error-handling> -->`
398	```python
399	`def 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
435	`Formatting 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
452	`Specify tools and configurations:`
453
454	````markdown
455	`## Linting`
456
457	`All Python code MUST pass Ruff checks:`
458
459	`<!-- <config-ruff> -->`
460	```toml
461	`[tool.ruff]`
462	`line-length = 88`
463	`target-version = "py311"`
464
465	`[tool.ruff.lint]`
466	`select = ["E", "F", "I", "N", "W", "UP"]`
467	`ignore = ["E501"] # Line too long (handled by formatter)`
468	```
469	`<!-- </config-ruff> -->`
470
471	Run: `ruff check . --fix`
472	````
473
474	`### Testing Requirements`
475
476	`Define 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
489	`import pytest`
490	`from pathlib import Path`
491	`from mymodule import process_file`
492
493	`def 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
503	`def 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
514	The `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`
528	`applyTo: '*/.py'`
529
530	`# Multiple extensions`
531	`applyTo: '*/.py, */.ipynb'`
532
533	`# Specific directory`
534	`applyTo: '/src//*.ts'`
535
536	`# Specific path pattern`
537	`applyTo: '*/.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
545	`Verify your glob pattern matches intended files:`
546
547	```bash
548	`# PowerShell`
549	`Get-ChildItem -Path . -Recurse -Include *.py`
550
551	`# Bash`
552	`find . -name "*.py"`
553	```
554
555	`## Validation Checklist`
556
557	`Before 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
619	`See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For instructions specifically:`
620
621	1. Verify `applyTo` glob pattern matches intended files
622	`2. Test all code examples execute correctly`
623	`3. Have Copilot generate code following your instructions`
624	`4. Validate specified linting/validation commands work`
625
626	`## Common Issues and Fixes`
627
628	`### Instructions-Specific Issues`
629
630	`### Invalid Glob Pattern`
631
632	Glob 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
636	Multiple 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
638	`For 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
642	`Run 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
649	`All 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
660	`See [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,`
670	`then carefully refined by our team of discerning human reviewers.*`
671	`<!-- markdownlint-enable MD036 -->`

microsoft/hve-core

Branches

Tags

Clone