Skip to content

Commit d839ae2

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

8 files changed

+1108
-0
lines changed

‎decisions/2025-07-10-centralized-package-version-management.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
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+
- "Directory.Packages.props"
10+
- "**/*.csproj"
11+
- "**/*.fsproj"
12+
- "**/*.vbproj"
13+
14+
<!-- The date this ADR was initially created in YYYY-MM-DD format. -->
15+
created: 2025-07-10
16+
17+
<!--
18+
The most recent date this ADR was updated in YYYY-MM-DD format.
19+
IMPORTANT: Update this field whenever the decision is modified.
20+
-->
21+
lastModified: 2025-07-14
22+
23+
<!--
24+
The current state of this ADR. If superseded, include references to the superseding ADR.
25+
Valid values: proposed, accepted, deprecated, superseded
26+
-->
27+
state: accepted
28+
29+
<!--
30+
A compact AI LLM compatible definition of this decision.
31+
This should be a precise, structured description that AI systems can easily parse and understand.
32+
Include the core decision, key rationale, and primary impact in 1-2 concise sentences.
33+
-->
34+
instructions: |
35+
Enable centralized package version management by setting ManagePackageVersionsCentrally to true in Directory.Packages.props to eliminate version inconsistencies and reduce maintenance overhead.
36+
All projects reference packages without version numbers, with versions controlled centrally from a single source of truth.
37+
---
38+
# Decision: Centralized Package Version Management with ManagePackageVersionsCentrally
39+
40+
We have decided to enable centralized package version management across the entire solution by setting `ManagePackageVersionsCentrally` to `true` in the `Directory.Packages.props` file.
41+
42+
## Context
43+
44+
In multi-project .NET solutions, managing NuGet package versions can become challenging and error-prone. Common issues include:
45+
46+
- **Version Inconsistencies**: Different projects in the same solution referencing different versions of the same package, leading to potential compatibility issues and unexpected behavior.
47+
- **Maintenance Overhead**: Updating package versions requires modifying multiple project files individually, increasing the risk of missing updates or introducing inconsistencies.
48+
- **Dependency Conflicts**: Transitive dependencies can introduce version conflicts when projects use different versions of packages that depend on the same underlying libraries.
49+
- **Security Vulnerabilities**: Difficulty in ensuring all projects use the latest secure versions of packages across the entire solution.
50+
- **Build and Runtime Issues**: Version mismatches can cause build failures, runtime exceptions, or subtle bugs that are difficult to diagnose.
51+
52+
Our template-dotnet project serves as a foundation for multiple .NET projects and needs to establish consistent package management practices from the start.
53+
54+
## Decision
55+
56+
We have implemented centralized package version management by:
57+
58+
1. **Enabling `ManagePackageVersionsCentrally`**: Set to `true` in `Directory.Packages.props` to enable MSBuild's central package management feature.
59+
2. **Enabling `CentralPackageTransitivePinningEnabled`**: Set to `true` to ensure transitive dependencies are also managed centrally and pinned to specific versions.
60+
3. **Defining Global Package References**: All common packages (analyzers, build tools, etc.) are defined once in `Directory.Packages.props` with specific versions.
61+
4. **Version-only Management**: Individual project files reference packages without version numbers, with versions controlled centrally.
62+
63+
This approach ensures that all projects in the solution use consistent package versions while maintaining a single source of truth for version management.
64+
65+
## Consequences
66+
67+
### Positive Consequences
68+
69+
- **Consistency**: All projects in the solution use the same versions of shared packages, eliminating version conflicts.
70+
- **Simplified Maintenance**: Package updates only require changes in one location (`Directory.Packages.props`).
71+
- **Better Security Posture**: Easier to ensure all projects use the latest secure versions of packages.
72+
- **Reduced Build Issues**: Eliminates version-related build failures and runtime conflicts.
73+
- **Improved Developer Experience**: Developers don't need to worry about package versions when adding references to existing packages.
74+
- **Transitive Dependency Control**: With `CentralPackageTransitivePinningEnabled`, even indirect dependencies are controlled and predictable.
75+
76+
### Potential Negative Consequences
77+
78+
- **Learning Curve**: Developers unfamiliar with central package management may need time to adapt.
79+
- **Flexibility Reduction**: Individual projects cannot override package versions without modifying the central configuration.
80+
- **Migration Complexity**: Existing projects may require significant changes to adopt this pattern.
81+
82+
## Alternatives Considered
83+
84+
### 1. Traditional Per-Project Package Management
85+
86+
**Description**: Allow each project to manage its own package versions independently.
87+
88+
**Why Not Chosen**:
89+
- Leads to version inconsistencies across the solution
90+
- Increases maintenance overhead
91+
- Higher risk of dependency conflicts
92+
- Difficult to ensure security updates are applied consistently
93+
94+
### 2. Shared MSBuild Props Files Without Central Management
95+
96+
**Description**: Use shared `.props` files to define common package versions but still reference versions in individual projects.
97+
98+
**Why Not Chosen**:
99+
- Still requires version references in each project file
100+
- More complex to implement and maintain
101+
- Doesn't leverage MSBuild's built-in central package management features
102+
- Less enforceable than the native MSBuild approach
103+
104+
### 3. Package Version Variables
105+
106+
**Description**: Define package versions as MSBuild properties and reference them in individual projects.
107+
108+
**Why Not Chosen**:
109+
- Verbose syntax in project files
110+
- No built-in tooling support
111+
- More error-prone than the centralized approach
112+
- Doesn't address transitive dependency management
113+
114+
## Related Decisions
115+
116+
- [GitVersion for Automated Semantic Versioning](./2025-07-10-gitversion-automated-semantic-versioning.md) - Related because centralized package management supports automated versioning by ensuring consistent dependency versions across the solution

‎decisions/2025-07-10-conventional-commits.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
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+
- "**/*.*"
10+
11+
<!-- The date this ADR was initially created in YYYY-MM-DD format. -->
12+
created: 2025-07-10
13+
14+
<!--
15+
The most recent date this ADR was updated in YYYY-MM-DD format.
16+
IMPORTANT: Update this field whenever the decision is modified.
17+
-->
18+
lastModified: 2025-07-14
19+
20+
<!--
21+
The current state of this ADR. If superseded, include references to the superseding ADR.
22+
Valid values: proposed, accepted, deprecated, superseded
23+
-->
24+
state: accepted
25+
26+
<!--
27+
A compact AI LLM compatible definition of this decision.
28+
This should be a precise, structured description that AI systems can easily parse and understand.
29+
Include the core decision, key rationale, and primary impact in 1-2 concise sentences.
30+
-->
31+
instructions: |
32+
Adopt Conventional Commits 1.0.0 specification for structured commit messages with type, scope, and description format to enable automated semantic versioning and changelog generation.
33+
Required types include feat, fix, docs, style, refactor, test, chore, build, ci, perf, and revert with breaking change indicators.
34+
---
35+
<!-- REQUIRED: Filename MUST follow the format: YYYY-MM-DD-Title (replace all spaces with hyphens) -->
36+
# Conventional Commits
37+
38+
A decision to adopt the Conventional Commits specification for standardizing commit messages across the project to improve automation, semantic versioning, and change communication.
39+
40+
## Context
41+
42+
The project currently lacks a standardized approach to commit messages, which creates several challenges:
43+
44+
1. **Inconsistent commit history**: Developers use different styles and formats for commit messages, making it difficult to understand the nature and impact of changes
45+
2. **Manual versioning**: Without structured commit messages, determining semantic version bumps requires manual analysis of changes
46+
3. **Changelog generation**: Creating release notes and changelogs is a manual process that is time-consuming and error-prone
47+
4. **Automated tooling limitations**: The lack of structured commit messages prevents the use of automated tools for CI/CD, semantic versioning, and release management
48+
5. **Communication gaps**: Unclear commit messages make it difficult for team members and stakeholders to understand the impact of changes
49+
50+
The project already uses GitVersion (as evidenced by `GitVersion.MsBuild` in `Directory.Packages.props`) and follows centralized package management, indicating a preference for automation and structured development practices.
51+
52+
## Decision
53+
54+
We will adopt the [Conventional Commits 1.0.0 specification](https://www.conventionalcommits.org/en/v1.0.0/) for all commit messages in this project.
55+
56+
**Commit Message Structure:**
57+
```
58+
<type>[optional scope]: <description>
59+
60+
[optional body]
61+
62+
[optional footer(s)]
63+
```
64+
65+
**Required Types:**
66+
- `feat`: A new feature (correlates with MINOR in Semantic Versioning)
67+
- `fix`: A bug fix (correlates with PATCH in Semantic Versioning)
68+
- `BREAKING CHANGE`: Breaking API changes (correlates with MAJOR in Semantic Versioning)
69+
70+
**Recommended Additional Types:**
71+
- `build`: Changes to build system or external dependencies
72+
- `chore`: Maintenance tasks that don't modify src or test files
73+
- `ci`: Changes to CI configuration files and scripts
74+
- `docs`: Documentation changes
75+
- `style`: Code style changes (formatting, missing semicolons, etc.)
76+
- `refactor`: Code changes that neither fix bugs nor add features
77+
- `perf`: Performance improvements
78+
- `test`: Adding or modifying tests
79+
80+
**Implementation Guidelines:**
81+
- Commits MUST be prefixed with a type followed by an optional scope, optional `!`, and required terminal colon and space
82+
- Breaking changes MUST be indicated either by `!` after the type/scope or by including `BREAKING CHANGE:` in the footer
83+
- Scope MAY be provided to give additional context (e.g., `feat(api):`, `fix(parser):`)
84+
- Description MUST immediately follow the colon and space after the type/scope prefix
85+
- Body and footers are OPTIONAL and provide additional context when needed
86+
87+
## Consequences
88+
89+
**Positive Consequences:**
90+
1. **Automated versioning**: GitVersion and other tools can automatically determine semantic version bumps based on commit types
91+
2. **Automated changelog generation**: Tools can automatically generate changelogs and release notes from structured commit messages
92+
3. **Improved communication**: Clear, structured commit messages help team members and stakeholders understand the nature and impact of changes
93+
4. **Better CI/CD integration**: Automated tools can trigger appropriate build and deployment processes based on commit types
94+
5. **Consistent commit history**: Standardized format makes the project history more readable and searchable
95+
6. **Enhanced collaboration**: New contributors can quickly understand the commit convention and follow established patterns
96+
97+
**Potential Challenges:**
98+
1. **Learning curve**: Team members need to learn and remember the conventional commit format
99+
2. **Enforcement overhead**: Initial effort required to establish tooling and processes to enforce the convention
100+
3. **Commit message length**: Some developers may need to adjust to writing more descriptive commit messages
101+
4. **Retroactive application**: Existing commit history will not follow the convention, creating inconsistency in historical data
102+
103+
**Risk Mitigation:**
104+
- Implement commit message linting tools to validate format automatically
105+
- Provide training and documentation for team members
106+
- Use commit message templates in development environments
107+
- Consider squash-and-merge workflow for pull requests to allow maintainers to create properly formatted commit messages
108+
109+
## Alternatives Considered
110+
111+
### 1. Custom Commit Convention
112+
113+
**Description**: Develop a project-specific commit message convention tailored to our needs.
114+
115+
**Pros**: Complete control over format and requirements, can be optimized for specific project needs
116+
117+
**Cons**: Requires documentation and training, no existing tooling support, reinventing the wheel, lacks community standards
118+
119+
**Rejection Reason**: Conventional Commits is already a well-established standard with extensive tooling support
120+
121+
### 2. Continue with Free-form Commit Messages
122+
123+
**Description**: Maintain the current approach of allowing developers to write commit messages without specific formatting requirements.
124+
125+
**Pros**: No learning curve, no enforcement overhead, developer freedom
126+
127+
**Cons**: Inconsistent history, no automation benefits, poor communication, manual versioning and changelog generation
128+
129+
**Rejection Reason**: Does not address the identified problems and prevents automation benefits
130+
131+
### 3. GitHub Flow with Descriptive PR Titles
132+
133+
**Description**: Focus on descriptive pull request titles and use squash merging to create clean commit messages.
134+
135+
**Pros**: Reduces individual commit message burden, maintains clean main branch history
136+
137+
**Cons**: Still lacks standardization, no automation benefits, requires manual formatting of squash commit messages
138+
139+
**Rejection Reason**: Does not provide the structured format needed for automation tools
140+
141+
### 4. Semantic Commit Messages (Alternative Format)
142+
143+
**Description**: Use alternative structured commit formats like Angular commit convention or other semantic formats.
144+
145+
**Pros**: Similar benefits to Conventional Commits, some tooling support
146+
147+
**Cons**: Less standardized than Conventional Commits, smaller ecosystem, potential compatibility issues
148+
149+
**Rejection Reason**: Conventional Commits is more widely adopted and has better tooling ecosystem
150+
151+
## Related Decisions
152+
153+
- [Centralized Package Version Management](./2025-07-10-centralized-package-version-management.md) - The adoption of centralized package management demonstrates the project's commitment to automation and standardization, which aligns with adopting Conventional Commits for automated versioning and release management
154+
- [GitVersion for Automated Semantic Versioning](./2025-07-10-gitversion-automated-semantic-versioning.md) - GitVersion is configured to parse conventional commit messages and automatically determine semantic version increments, making conventional commits essential for automated versioning to work correctly

0 commit comments

Comments
 (0)