Skip to content

Commit 0d019c8

Browse files
samtrionsamtrion
committed
chore(template): sync with dailydevops/template-dotnet [skip ci]
1 parent bf89ba4 commit 0d019c8

3 files changed

Lines changed: 346 additions & 1 deletion

File tree

‎.github/prompts/create-architectural-decision-record.prompt.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
agent: 'agent'
33
description: 'Create an Architectural Decision Record (ADR) document optimized for decision documentation.'
4-
tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'vscode/extensions', 'fetch/*', 'fetch/fetch', 'web/fetch', 'web/githubRepo', 'vscode/openSimpleBrowser', 'read/problems', 'execute/createAndRunTask', 'execute/runTask', 'read/getTaskOutput', 'search', 'search/searchResults', 'read/terminalLastCommand', 'read/terminalSelection', 'execute/testFailure', 'search/usages', 'vscode/vscodeAPI']
4+
tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'vscode/extensions', 'fetch/*', 'fetch/fetch', 'web/fetch', 'web/githubRepo', 'vscode/openSimpleBrowser', 'read/problems', 'execute/createAndRunTask', 'execute/runTask', 'read/getTaskOutput', 'search', 'search/searchResults', 'read/terminalLastCommand', 'read/terminalSelection', 'execute/testFailure', 'search/usages', 'vscode/vscodeAPI', 'edit/createFile', 'read/readFile']
55
---
66
# Create Architectural Decision Record
77

‎decisions/2026-01-09-nuget-package-readme-template.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
<!-- List of authors who contributed to this decision. Include full names and roles if applicable. -->
2+
authors:
3+
- Martin Stühmer
4+
5+
<!--
6+
The patterns this decision applies to. Each entry is a glob pattern that matches files affected by this decision.
7+
-->
8+
applyTo:
9+
- "**/README.md"
10+
- "src/**/README.md"
11+
12+
<!-- The date this ADR was initially created in YYYY-MM-DD format. -->
13+
created: 2026-01-09
14+
15+
<!--
16+
The most recent date this ADR was updated in YYYY-MM-DD format.
17+
IMPORTANT: Update this field whenever the decision is modified.
18+
-->
19+
lastModified: 2026-01-09
20+
21+
<!--
22+
The current state of this ADR. If superseded, include references to the superseding ADR.
23+
Valid values: proposed, accepted, deprecated, superseded
24+
-->
25+
state: accepted
26+
27+
<!--
28+
A compact AI LLM compatible definition of this decision.
29+
This should be a precise, structured description that AI systems can easily parse and understand.
30+
Include the core decision, key rationale, and primary impact in 1-2 concise sentences.
31+
-->
32+
instructions: |
33+
Use templates/readme-project.md as the mandatory template for all NuGet package README files to ensure consistent documentation structure, comprehensive content, and absolute URLs for cross-platform compatibility.
34+
All project READMEs MUST include features, installation instructions, usage examples, requirements, and support information following the template structure.
35+
MUST preserve all automated content markers (e.g., <!-- packages:start -->) under all circumstances when updating existing README files.
36+
---
37+
<!-- REQUIRED: Filename MUST follow the format: YYYY-MM-DD-Title (replace all spaces with hyphens) -->
38+
# NuGet Package README Template
39+
40+
Establish a standardized template for NuGet package README files to ensure consistent, comprehensive, and professional documentation across all packages in the project ecosystem.
41+
42+
## Context
43+
44+
NuGet packages require clear and comprehensive documentation to help users understand the package functionality, installation process, and usage patterns. Without a standardized template, several issues arise:
45+
46+
1. **Inconsistent Documentation**: Different packages have varying documentation quality and structure, making it difficult for users to find information consistently across packages
47+
2. **Missing Critical Information**: Ad-hoc README files often omit essential sections such as requirements, configuration, or troubleshooting guidance
48+
3. **URL Management**: Relative URLs break when viewed on NuGet.org, GitHub, or other platforms that display README content in different contexts
49+
4. **Maintenance Overhead**: Without a template, maintaining documentation standards requires manual review and correction of each README file
50+
5. **Onboarding Complexity**: New contributors and package authors must determine documentation structure and content independently, leading to variations and potential gaps
51+
6. **Professional Appearance**: Inconsistent documentation reduces the perceived quality and professionalism of packages
52+
7. **Discoverability**: Well-structured documentation with standard sections improves package discoverability and user adoption
53+
54+
The need for a standardized approach became apparent as the project ecosystem expanded with multiple NuGet packages requiring consistent documentation standards.
55+
56+
## Decision
57+
58+
All NuGet package README files MUST use the standardized template located at `templates/readme-project.md` as the foundation for project documentation.
59+
60+
The template provides a comprehensive structure including:
61+
62+
* **Package Metadata**: Badges for version, downloads, and license status
63+
* **Project Description**: Clear explanation of package purpose and functionality
64+
* **Features**: Bullet-point list of key capabilities
65+
* **Installation Instructions**: Multiple installation methods (NuGet Package Manager, .NET CLI, PackageReference)
66+
* **Quick Start**: Minimal working example for immediate usage
67+
* **Usage Examples**: Detailed examples covering basic and advanced scenarios
68+
* **Configuration**: Setup and configuration guidance
69+
* **Requirements**: Minimum framework versions and dependencies
70+
* **Related Packages**: Cross-references to related packages in the ecosystem
71+
* **Documentation Links**: References to comprehensive documentation
72+
* **Contributing Guidelines**: Links to contribution processes
73+
* **Support Channels**: GitHub Issues, Discussions, and documentation links
74+
* **License Information**: Clear license declaration and reference
75+
76+
All URLs in package READMEs MUST be absolute URLs pointing to GitHub or NuGet.org to ensure compatibility across all platforms where the README may be displayed.
77+
78+
The template includes comprehensive comments explaining each section's purpose and providing guidance for content creation.
79+
80+
### Preservation of Automated Content Markers
81+
82+
When updating existing README files, all automated content markers MUST be preserved under all circumstances. These markers are HTML comments that define sections managed by automated tools or processes.
83+
84+
Common marker patterns include:
85+
* `<!-- packages:start -->` and `<!-- packages:end -->` - Automated package list sections
86+
* `<!-- section:start -->` and `<!-- section:end -->` - Generic automated sections
87+
* Any other `<!-- marker:start -->` and `<!-- marker:end -->` pairs
88+
89+
These markers and their content MUST NOT be modified or removed during manual template updates. Automated tools rely on these markers to maintain dynamic content sections.
90+
91+
## Consequences
92+
93+
### Positive
94+
95+
* **Consistency**: All package READMEs follow the same structure, making information easy to find
96+
* **Completeness**: Template ensures all critical sections are included and properly documented
97+
* **Professional Quality**: Standardized documentation improves the perceived quality and professionalism of all packages
98+
* **Reduced Maintenance**: Template updates automatically improve documentation guidance for all packages
99+
* **Cross-Platform Compatibility**: Absolute URLs ensure README content displays correctly on NuGet.org, GitHub, and other platforms
100+
* **Faster Onboarding**: New package authors have clear guidance for creating documentation
101+
* **Better Discoverability**: Consistent structure with badges and clear descriptions improves package discoverability
102+
* **User Experience**: Users benefit from predictable documentation structure across all packages
103+
* **Quality Assurance**: Template comments guide authors toward complete and accurate documentation
104+
* **Automated Content Protection**: Marker preservation ensures automated tooling continues to function correctly
105+
106+
### Negative
107+
108+
* **Initial Effort**: Existing packages require updates to conform to the new template structure
109+
* **Flexibility Constraints**: Specialized packages may need to deviate from the standard template structure
110+
* **Maintenance Obligation**: Template changes require updating existing package READMEs to maintain consistency
111+
* **Learning Curve**: Authors must familiarize themselves with the template structure and guidelines
112+
* **Marker Awareness**: Authors must be aware of automated content markers and avoid modifying them manually
113+
114+
## Alternatives Considered
115+
116+
### Manual Documentation Without Template
117+
118+
Each package author creates README files independently without a standardized template.
119+
120+
**Rejected because**:
121+
* Leads to inconsistent documentation quality and structure
122+
* Critical information often omitted or poorly organized
123+
* Increases maintenance burden for ensuring documentation standards
124+
* Reduces professional appearance of package ecosystem
125+
* Makes it difficult for users to find information consistently
126+
127+
### Minimal Template
128+
129+
Provide a minimal template with only basic sections (title, description, installation).
130+
131+
**Rejected because**:
132+
* Insufficient guidance for comprehensive documentation
133+
* Important sections like configuration, requirements, and support would be frequently omitted
134+
* Does not address cross-platform URL compatibility issues
135+
* Provides less value in standardizing documentation quality
136+
137+
### Multiple Templates by Package Type
138+
139+
Create different templates for different types of packages (libraries, tools, extensions).
140+
141+
**Rejected because**:
142+
* Adds complexity in choosing the correct template
143+
* Reduces consistency across the package ecosystem
144+
* Most sections are relevant to all package types
145+
* Authors can omit irrelevant sections from the standard template
146+
147+
### External Documentation Generation Tools
148+
149+
Use automated documentation generation tools (DocFX, Sandcastle) instead of manual README files.
150+
151+
**Rejected because**:
152+
* NuGet.org displays README content prominently, requiring manually crafted content
153+
* Generated documentation is often too technical or detailed for quick package evaluation
154+
* Adds build complexity and tooling dependencies
155+
* Does not replace the need for user-friendly introductory content
156+
157+
## Related Decisions
158+
159+
* [English as Project Language](./2025-07-11-english-as-project-language.md) - All README content must be written in English following this decision
160+
* [Folder Structure and Naming Conventions](./2025-07-10-folder-structure-and-naming-conventions.md) - README files are placed at the root of each project directory following folder structure conventions

‎templates/readme-project.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Project Name <!-- Replace with actual project/package name -->
2+
3+
<!--
4+
Replace 'YourPackageName' with the actual NuGet package ID.
5+
Replace 'YourRepo' with the actual GitHub repository name.
6+
The badges provide quick visual indicators of package status.
7+
-->
8+
[![NuGet Version](https://img.shields.io/nuget/v/YourPackageName.svg)](https://www.nuget.org/packages/YourPackageName/)
9+
[![NuGet Downloads](https://img.shields.io/nuget/dt/YourPackageName.svg)](https://www.nuget.org/packages/YourPackageName/)
10+
[![License](https://img.shields.io/github/license/dailydevops/YourRepo.svg)](https://github.com/dailydevops/YourRepo/blob/main/LICENSE)
11+
12+
<!--
13+
Provide a brief 1-2 sentence description of what this project/package does and its primary purpose.
14+
Focus on the problem it solves and the target audience.
15+
Example: "A high-performance logging framework for .NET applications that simplifies structured logging and provides seamless integration with popular logging providers."
16+
-->
17+
18+
## Features
19+
20+
<!--
21+
List the key features and capabilities of this project. Use bullet points for clarity.
22+
Focus on user-facing benefits, not implementation details.
23+
Start each feature with a strong action verb or noun.
24+
Limit to 5-8 key features to maintain focus.
25+
Examples:
26+
* High-performance async/await support for non-blocking operations
27+
* Built-in dependency injection integration
28+
* Comprehensive logging and diagnostics
29+
-->
30+
31+
* Feature 1 - Brief description of what this feature provides
32+
* Feature 2 - Brief description of what this feature provides
33+
* Feature 3 - Brief description of what this feature provides
34+
35+
## Installation
36+
37+
<!-- Replace 'YourPackageName' and 'x.x.x' with actual values in all installation methods below. -->
38+
39+
### NuGet Package Manager
40+
41+
```powershell
42+
Install-Package YourPackageName
43+
```
44+
45+
### .NET CLI
46+
47+
```bash
48+
dotnet add package YourPackageName
49+
```
50+
51+
### PackageReference
52+
53+
<!-- For PackageReference, you can either specify a version or omit it if using centralized package management. -->
54+
```xml
55+
<PackageReference Include="YourPackageName" Version="x.x.x" />
56+
```
57+
58+
## Quick Start
59+
60+
<!--
61+
Provide a minimal working example that demonstrates the core functionality.
62+
This should be copy-paste ready code that users can run immediately.
63+
Include necessary using statements and basic setup.
64+
Keep it simple - focus on the most common use case.
65+
Replace 'YourNamespace', 'YourService', and method names with actual values.
66+
-->
67+
68+
```csharp
69+
// Example code demonstrating basic usage
70+
using YourNamespace;
71+
72+
// Initialize and use the main functionality
73+
var service = new YourService();
74+
var result = await service.DoSomethingAsync();
75+
```
76+
77+
## Usage
78+
79+
<!--
80+
Provide more detailed usage examples covering the main scenarios.
81+
Add as many subsections as needed to cover different use cases.
82+
Each example should be complete and runnable.
83+
Include comments explaining what each section does.
84+
Common patterns:
85+
- Basic Example: Simple, straightforward usage
86+
- Advanced Example: Complex scenarios with multiple features
87+
- Integration Example: Using with other libraries or frameworks
88+
-->
89+
90+
### Basic Example
91+
92+
```csharp
93+
// Detailed example showing typical usage
94+
// Replace with actual working code
95+
```
96+
97+
### Advanced Example
98+
99+
```csharp
100+
// Example demonstrating advanced features or configuration
101+
// Replace with actual working code showing complex scenarios
102+
```
103+
104+
## Configuration
105+
106+
<!--
107+
If applicable, describe configuration options and how to use them.
108+
Include examples for different configuration methods:
109+
- Code-based configuration
110+
- appsettings.json configuration
111+
- Environment variables
112+
- Dependency injection setup
113+
Remove this section if the package doesn't require configuration.
114+
-->
115+
116+
```csharp
117+
// Example configuration
118+
// Replace with actual configuration code
119+
```
120+
121+
## Requirements
122+
123+
<!--
124+
List the minimum requirements for using this package.
125+
Include:
126+
- Target framework(s) - e.g., .NET 8.0, .NET Standard 2.0
127+
- Required dependencies (if any critical ones)
128+
- System requirements (OS, hardware, etc.)
129+
- Runtime requirements (ASP.NET Core, Windows-specific features, etc.)
130+
Replace 'X.0' with the actual minimum .NET version.
131+
-->
132+
133+
* .NET X.0 or higher
134+
* Any additional dependencies or system requirements
135+
136+
## Related Packages
137+
138+
<!--
139+
List related packages from the same project family or ecosystem.
140+
Include NuGet links and brief descriptions (one line each).
141+
Use absolute URLs to NuGet.org.
142+
Focus on packages that complement or extend this package's functionality.
143+
Remove this section if there are no related packages.
144+
Replace example entries with actual related packages.
145+
-->
146+
147+
* [**RelatedPackage.Core**](https://www.nuget.org/packages/RelatedPackage.Core/) - Core functionality and shared abstractions
148+
* [**RelatedPackage.Extensions**](https://www.nuget.org/packages/RelatedPackage.Extensions/) - Additional extensions and helper methods
149+
* [**RelatedPackage.Integrations**](https://www.nuget.org/packages/RelatedPackage.Integrations/) - Integration with third-party libraries
150+
151+
## Documentation
152+
153+
<!-- Replace 'YourRepo' with the actual repository name. Add links to any additional documentation sites if available. -->
154+
For complete documentation, please visit the [official documentation](https://github.com/dailydevops/YourRepo/blob/main/README.md).
155+
156+
## Contributing
157+
158+
<!-- Ensure the CONTRIBUTING.md file exists in the repository before using this link. -->
159+
Contributions are welcome! Please read the [Contributing Guidelines](https://github.com/dailydevops/YourRepo/blob/main/CONTRIBUTING.md) before submitting a pull request.
160+
161+
## Support
162+
163+
<!-- Replace 'YourRepo' with the actual repository name in all links below. -->
164+
* **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/dailydevops/YourRepo/issues)
165+
* **Discussions**: Join the conversation on [GitHub Discussions](https://github.com/dailydevops/YourRepo/discussions)
166+
* **Documentation**: Read the full documentation at [https://github.com/dailydevops/YourRepo](https://github.com/dailydevops/YourRepo)
167+
168+
## License
169+
170+
<!-- Replace 'MIT License' and 'YourRepo' with actual values. Ensure the LICENSE file exists in the repository. -->
171+
This project is licensed under the MIT License - see the [LICENSE](https://github.com/dailydevops/YourRepo/blob/main/LICENSE) file for details.
172+
173+
## Acknowledgments
174+
175+
<!--
176+
Optional: Credit contributors, libraries, or resources that helped with this project.
177+
Remove this section if not needed.
178+
Examples:
179+
- Thank specific contributors or organizations
180+
- Credit libraries or tools used
181+
- Acknowledge inspiration or related projects
182+
-->
183+
184+
> [!NOTE]
185+
> **Made with ❤️ by the NetEvolve Team**

0 commit comments

Comments
 (0)