Skip to content

Commit 8448ea7

Browse files
committed
chore(template): sync with dailydevops/dotnet-template [skip ci]
1 parent 9b25ee6 commit 8448ea7

File tree

1 file changed

+68
-0
lines changed

1 file changed

+68
-0
lines changed
Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
applyTo: '.github/copilot-instructions.md, .github/instructions/*.instructions.md, decisions/**/*.md'
3+
4+
description: 'This file contains instructions for wording and writing style.
5+
It includes guidelines for creating and modifying instruction files, decision documents, and Copilot instructions.
6+
Ensure to follow the practices outlined in this file to maintain consistency and clarity in documentation.'
7+
---
8+
9+
# Wording and Writing Style Instructions
10+
11+
## General Style
12+
13+
* MUST use clear, concise, and direct language.
14+
* MUST maintain a consistent formal, professional tone throughout all documentation.
15+
* MUST use active voice rather than passive voice (e.g., "Use this pattern" instead of "This pattern should be used").
16+
* MUST use present tense for instructions and guidelines.
17+
* MUST format headings using Title Case.
18+
* MUST format all documentation in proper Markdown.
19+
20+
## Directive Language
21+
22+
* MUST use modal verbs to indicate requirements clearly:
23+
- **MUST**: Required, mandatory action or rule
24+
- **SHOULD**: Recommended action but not mandatory
25+
- **MAY**: Optional action
26+
- **MUST NOT** or **MUST NEVER**: Prohibited action
27+
* MUST place the directive at the beginning of the bullet point or sentence.
28+
* MUST maintain consistent formatting of directives (all caps).
29+
30+
## Instruction Files
31+
32+
* MUST include a YAML frontmatter section with `applyTo` and `description` fields.
33+
* MUST organize content under clear, hierarchical headings.
34+
* MUST use bullet points for individual instructions within each section.
35+
* MUST provide concrete examples where appropriate.
36+
* MUST use code formatting (backticks) for code, file names, and technical terms.
37+
* MUST include both general principles and specific implementation details.
38+
39+
## Decision Documents
40+
41+
* MUST follow the established ADR (Architecture Decision Record) format.
42+
* MUST include all required frontmatter fields: authors, applyTo, created, lastModified, state.
43+
* MUST provide clear context and problem statements.
44+
* MUST explicitly state the decision and its implications.
45+
* MUST use consistent terminology when referring to technical concepts.
46+
47+
## Copilot Instructions
48+
49+
* MUST structure guidance as imperative statements.
50+
* MUST group related instructions under appropriate section headings.
51+
* MUST explicitly state constraints and limitations.
52+
* MUST reference specific file paths, folders, or patterns when applicable.
53+
* MUST include cross-references to related decisions or instruction files when appropriate.
54+
55+
## Examples and References
56+
57+
* MUST use code blocks with appropriate language specifiers for code examples.
58+
* MUST use relative links when referencing other documents within the repository.
59+
* SHOULD include brief explanatory comments for complex code examples.
60+
* SHOULD provide references to external resources when applicable.
61+
62+
## Formatting Conventions
63+
64+
* MUST use a single blank line to separate paragraphs.
65+
* MUST use a single blank line before and after lists, code blocks, and headings.
66+
* MUST use consistent indentation (2 spaces) for nested list items.
67+
* MUST use consistent bullet point symbols (* for primary bullets, - for secondary).
68+
* MUST use proper nesting of headings (H1 for title, H2 for major sections, H3 for subsections).

0 commit comments

Comments
 (0)