Skip to content

Commit fe6304d

Browse files
samtrionsamtrion
authored
feat: Reorganized solution and cleanedup the configurations (#183)
* feat: Restructured and cleanup the solution * style: Rebuild / reformatted solution * docs: Modernized the documentation
1 parent 9776bdb commit fe6304d

34 files changed

Lines changed: 1432 additions & 162 deletions

‎.editorconfig‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ generated_code = true
4444
# XML project files
4545
[*.{slnx,csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj,nativeproj,locproj}]
4646
indent_size = 2
47+
max_line_length = 160
4748

4849
# Xml build files
4950
[*.builds]

‎README.md‎

Lines changed: 182 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,187 @@
11
# NetEvolve.Defaults
22

3-
This is the NetEvolve.Defaults package, which provides the standard configurations and settings for the NetEvolve projects. Such as `.editorconfig`, build props and targets.
4-
All of our projects are build on top of this package, so we can have a consistent build process and settings across all of our projects.
3+
NetEvolve.Defaults is a comprehensive enterprise-grade build automation and configuration platform that establishes consistent development standards across all NetEvolve projects. It provides unified build properties, standardized configuration files, integrated code analysis, and development guidelines that enforce quality, consistency, and best practices throughout your entire project ecosystem.
4+
5+
## Overview
6+
7+
This repository contains a complete infrastructure for maintaining code quality and consistency across distributed teams and projects. It encompasses:
8+
9+
### Core Components
10+
11+
- **[NetEvolve.Defaults](https://www.nuget.org/packages/NetEvolve.Defaults)**: The foundational build configuration package providing MSBuild properties, targets, and shared settings
12+
- **[NetEvolve.Defaults.Analyzer](https://www.nuget.org/packages/NetEvolve.Defaults.Analyzer)**: A comprehensive Roslyn-based diagnostic analyzer enforcing NuGet package quality standards
13+
- **Build & Configuration Files**: Centralized editor configuration, version management, and continuous integration settings
14+
15+
### Key Features
16+
17+
- **Centralized Build Configuration**: Unified project settings and compilation options for single and multi-targeted projects
18+
- **Code Analysis & Quality Enforcement**: Automated static analysis with Roslyn analyzers and code style enforcement via `.editorconfig`
19+
- **Modern Language Features**: C# 13 language features with nullable reference types, implicit usings, and file-scoped namespaces
20+
- **Continuous Integration Support**: Automatic detection and optimization for CI/CD environments with GitVersion integration
21+
- **NuGet Security Auditing**: Integrated vulnerability scanning for package dependencies via NuGet Audit
22+
- **Semantic Versioning**: Automated semantic versioning powered by GitVersion for consistent version management
23+
- **Package Quality Standards**: Enforced NuGet metadata validation ensuring professional package documentation and discoverability
24+
- **Multi-Framework Support**: Seamless configuration for projects targeting multiple .NET frameworks
25+
26+
## Quick Start
27+
28+
### Installation
29+
30+
Install the core package in your project:
531

6-
## Installation
7-
To install this package, you can use the following command:
832
```bash
933
dotnet add package NetEvolve.Defaults
10-
```
34+
```
35+
36+
For enhanced package quality validation, also add the analyzer:
37+
38+
```bash
39+
dotnet add package NetEvolve.Defaults.Analyzer
40+
```
41+
42+
### Manual Configuration
43+
44+
Add to your project file (`.csproj`, `.fsproj`, or `.vbproj`):
45+
46+
```xml
47+
<ItemGroup>
48+
<PackageReference Include="NetEvolve.Defaults" Version="x.x.x" PrivateAssets="all" />
49+
<PackageReference Include="NetEvolve.Defaults.Analyzer" Version="x.x.x" PrivateAssets="all" />
50+
</ItemGroup>
51+
```
52+
53+
The `PrivateAssets="all"` attribute ensures that these build utilities are only applied to your project and not propagated to consumers of your packages.
54+
55+
## Repository Structure
56+
57+
```
58+
defaults/
59+
├── src/
60+
│ ├── NetEvolve.Defaults/ # Core build configuration package
61+
│ └── NetEvolve.Defaults.Analyzer/ # NuGet package quality analyzer
62+
├── tests/
63+
│ └── NetEvolve.Defaults.Tests.Integration/ # Integration tests
64+
├── docs/
65+
│ └── usage/ # Diagnostic rule documentation
66+
├── decisions/ # Architectural decision records
67+
├── .github/ # GitHub workflows and instructions
68+
├── Directory.Packages.props # Centralized NuGet version management
69+
├── Directory.Build.props # Global MSBuild properties
70+
├── Directory.Build.targets # Global MSBuild targets
71+
└── GitVersion.yml # Semantic versioning configuration
72+
```
73+
74+
## Included Packages
75+
76+
### NetEvolve.Defaults
77+
78+
The foundational package providing standardized build settings:
79+
80+
- **MSBuild Properties & Targets**: Consistent compilation configuration across all projects
81+
- **Editor Configuration**: Standardized code style rules via `.editorconfig`
82+
- **Analyzer Settings**: Pre-configured Roslyn analyzer rules matching enterprise standards
83+
- **NuGet Audit Integration**: Automated security vulnerability scanning
84+
- **Language Configuration**: Modern C# language features with sensible defaults
85+
86+
[Learn more about NetEvolve.Defaults →](https://www.nuget.org/packages/NetEvolve.Defaults)
87+
88+
### NetEvolve.Defaults.Analyzer
89+
90+
Comprehensive diagnostic analyzer for NuGet package quality:
91+
92+
- **Package Metadata Validation**: Ensures complete and professional package information
93+
- **Repository Configuration**: Validates repository URLs, issue trackers, and licensing
94+
- **Build Standards Enforcement**: Verifies compliance with modern build patterns
95+
- **Real-Time Diagnostics**: Immediate feedback during development with actionable fixes
96+
- **9+ Diagnostic Rules**: Covering critical package configuration aspects
97+
98+
[Learn more about NetEvolve.Defaults.Analyzer →](https://www.nuget.org/packages/NetEvolve.Defaults.Analyzer)
99+
100+
## Diagnostic Rules
101+
102+
The analyzer package enforces standardized quality checks via diagnostic rules. For detailed documentation on all rules and remediation steps:
103+
104+
- [NED0001-NED0009 Rules Documentation](https://github.com/dailydevops/defaults/tree/main/docs/usage)
105+
- [Diagnostic Configuration Guide](https://github.com/dailydevops/defaults/tree/main/src/NetEvolve.Defaults.Analyzer#diagnostic-rules)
106+
107+
## Configuration & Customization
108+
109+
All settings can be customized through:
110+
111+
1. **Project File Properties**: Override specific settings in individual `.csproj` files
112+
2. **Directory.Build.props**: Apply settings across all projects in a solution
113+
3. **.editorconfig**: Customize code style and formatting rules
114+
4. **.github/instructions**: Apply project-specific guidelines and conventions
115+
116+
### Common Customizations
117+
118+
**Enable Preview Language Features:**
119+
```xml
120+
<PropertyGroup>
121+
<LangVersion>preview</LangVersion>
122+
</PropertyGroup>
123+
```
124+
125+
**Disable Nullable Reference Types (Not Recommended):**
126+
```xml
127+
<PropertyGroup>
128+
<Nullable>disable</Nullable>
129+
</PropertyGroup>
130+
```
131+
132+
**Customize Target Frameworks:**
133+
```xml
134+
<PropertyGroup>
135+
<TargetFrameworks>net8.0;net9.0</TargetFrameworks>
136+
</PropertyGroup>
137+
```
138+
139+
## Best Practices
140+
141+
1. **Use PrivateAssets="all"**: Ensures build tools don't leak into package consumers
142+
2. **Enable Nullable Reference Types**: Improves type safety and reduces null reference exceptions
143+
3. **Use Implicit Usings**: Reduces boilerplate and improves code readability
144+
4. **Configure Complete Metadata**: Ensure all NuGet package properties are set for discoverability
145+
5. **Run Analyzers Regularly**: Address diagnostics during development, not at release time
146+
6. **Test Multi-Framework Projects**: Verify code works across all target frameworks
147+
148+
## Architectural Decisions
149+
150+
This project follows architectural principles documented in the [decisions/](https://github.com/dailydevops/defaults/tree/main/decisions) folder. Key decision areas include:
151+
152+
- **Folder Structure & Naming Conventions**: Consistent project organization
153+
- **Centralized Package Management**: Single source of truth for NuGet versions
154+
- **English as Project Language**: All code, documentation, and comments in English
155+
- **.NET 10 & C# 13 Adoption**: Modern language features and runtime support
156+
- **Conventional Commits**: Structured commit messages for automated versioning
157+
- **GitVersion Integration**: Automated semantic versioning from git history
158+
159+
For more details, see [Architectural Decisions](https://github.com/dailydevops/defaults/tree/main/decisions).
160+
161+
## Contributing
162+
163+
Contributions are welcome! When contributing to this project:
164+
165+
1. Follow the existing code style and conventions
166+
2. Ensure all diagnostic analyzers pass without warnings
167+
3. Update relevant documentation
168+
4. Follow [Conventional Commits](https://www.conventionalcommits.org/) format for commit messages
169+
5. Add tests for new functionality
170+
171+
## Support
172+
173+
For issues, feature requests, or questions:
174+
175+
- [GitHub Issues](https://github.com/dailydevops/defaults/issues)
176+
- [GitHub Discussions](https://github.com/dailydevops/defaults/discussions)
177+
178+
## Documentation
179+
180+
- [NetEvolve.Defaults Documentation](https://www.nuget.org/packages/NetEvolve.Defaults)
181+
- [NetEvolve.Defaults.Analyzer Documentation](https://www.nuget.org/packages/NetEvolve.Defaults.Analyzer)
182+
- [Diagnostic Rules Reference](https://github.com/dailydevops/defaults/tree/main/docs/usage)
183+
- [Architectural Decisions](https://github.com/dailydevops/defaults/tree/main/decisions)
184+
185+
## License
186+
187+
This project is licensed under the [MIT License](https://github.com/dailydevops/defaults/blob/main/LICENSE).

‎docs/usage/ned0001.md‎

Lines changed: 66 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,74 @@
1-
## Project configuration warning NED0001
1+
# NED0001: Missing Package ID Configuration
22

3-
The project file is missing or has an incomplete configuration for the `<PackageId />` tag. This tag is crucial as it uniquely identifies the package within the project, ensuring proper management and deployment. Without a valid `<PackageId />`, the build process may fail, leading to potential issues in package restoration and versioning.
3+
## Overview
44

5-
To resolve this issue, please follow these steps:
5+
**Severity**: Warning
6+
**Category**: Package Metadata
7+
**Applies To**: Packable Projects
68

7-
- Open the Project File: Locate and open your project file (e.g., `.csproj` for C# projects).
9+
## Description
810

9-
- Add or Update the `<PackageId />` Tag: Ensure that the `<PackageId />` tag is present and correctly formatted.
11+
The project file is missing or has an incomplete configuration for the `<PackageId />` property. This property uniquely identifies your NuGet package and is essential for proper package management, distribution, and versioning. Without a valid `<PackageId />`, the build process cannot properly create or publish your package.
1012

11-
It should look like this:
12-
```xml
13-
<PackageId>Your.Package.Id</PackageId>
14-
```
13+
## Impact
1514

16-
- Validate the Configuration: After making changes, validate the project file to ensure there are no syntax errors.
15+
- Package creation and publication will fail
16+
- Dependency resolution and version management may be compromised
17+
- Package consumers cannot reference your package reliably
18+
- Package discoverability on NuGet.org is impossible
1719

18-
- Rebuild the Project: Once the configuration is corrected, rebuild your project to confirm that the issue is resolved.
20+
## Resolution
1921

20-
If you continue to experience problems, consider checking the documentation for your specific project type or reaching out to your development team for further assistance. Proper configuration of the `<PackageId />` tag is essential for maintaining a smooth development workflow.
22+
### Step 1: Open Your Project File
23+
24+
Locate and open your project file (`.csproj`, `.fsproj`, or `.vbproj`).
25+
26+
### Step 2: Add or Update the PackageId Property
27+
28+
Ensure the `<PackageId />` property is present in your project's `<PropertyGroup>` section. Use a unique, meaningful identifier following these conventions:
29+
30+
- Use reverse domain notation (e.g., `Company.ProductName.ModuleName`)
31+
- Use PascalCase for segments
32+
- Use periods to separate segments
33+
- Keep it concise but descriptive
34+
35+
```xml
36+
<PropertyGroup>
37+
<PackageId>Your.Company.PackageName</PackageId>
38+
<!-- Additional properties -->
39+
</PropertyGroup>
40+
```
41+
42+
### Step 3: Validate and Rebuild
43+
44+
Validate your project file for syntax errors and rebuild your project:
45+
46+
```bash
47+
dotnet build
48+
```
49+
50+
## Best Practices
51+
52+
- Ensure the `<PackageId />` is unique across the NuGet ecosystem
53+
- Use a consistent naming scheme across related packages
54+
- Consider your package's purpose and domain in the naming
55+
- Avoid generic names that may conflict with existing packages
56+
57+
## Example
58+
59+
```xml
60+
<Project Sdk="Microsoft.NET.Sdk">
61+
<PropertyGroup>
62+
<TargetFramework>net8.0</TargetFramework>
63+
<PackageId>NetEvolve.Defaults</PackageId>
64+
<PackageVersion>1.0.0</PackageVersion>
65+
<Title>NetEvolve.Defaults</Title>
66+
<Description>Enterprise build configuration and standards package</Description>
67+
</PropertyGroup>
68+
</Project>
69+
```
70+
71+
## See Also
72+
73+
- [NuGet Package Metadata Reference](https://docs.microsoft.com/en-us/nuget/reference/msbuild-targets)
74+
- [Package Naming Conventions](https://docs.microsoft.com/en-us/nuget/concepts/package-naming-conventions)

‎docs/usage/ned0002.md‎

Lines changed: 61 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,69 @@
1-
## Project configuration warning NED0002
1+
# NED0002: Missing Package Title Configuration
22

3-
The project file is missing or has an incomplete configuration for the `<Title />` tag. This tag is essential as it defines the display name of your project, which is used in various contexts, including package management and user interfaces. An incomplete or absent `<Title />` can lead to confusion during deployment and may affect how users perceive your project.
3+
## Overview
44

5-
To resolve this issue, please follow these steps:
5+
**Severity**: Warning
6+
**Category**: Package Metadata
7+
**Applies To**: Packable Projects
68

7-
- Open the Project File: Locate and open your project file (e.g., `.csproj` for C# projects).
9+
## Description
810

9-
- Add or Update the `<Title />` Tag: Ensure that the `<Title />` tag is present and correctly formatted.
11+
The project file is missing or has an incomplete configuration for the `<Title />` property. This property defines the display name of your NuGet package as it appears on NuGet.org and in package management tools. A clear, descriptive title is essential for user discoverability and package recognition.
1012

11-
It should look like this:
12-
```xml
13-
<Title>Your Project Title</Title>
14-
```
13+
## Impact
1514

16-
- Validate the Configuration: After making changes, validate the project file to ensure there are no syntax errors.
15+
- Package displays with a generic or missing name on NuGet.org
16+
- Reduced visibility and discoverability for potential users
17+
- Professional appearance is compromised
18+
- Users cannot quickly understand the package's purpose
1719

18-
- Rebuild the Project: Once the configuration is corrected, rebuild your project to confirm that the issue is resolved.
20+
## Resolution
1921

20-
If you continue to experience problems, consider checking the documentation for your specific project type or reaching out to your development team for further assistance. Proper configuration of the `<Title />` tag is essential for maintaining a smooth development workflow.
22+
### Step 1: Open Your Project File
23+
24+
Locate and open your project file (`.csproj`, `.fsproj`, or `.vbproj`).
25+
26+
### Step 2: Add or Update the Title Property
27+
28+
Ensure the `<Title />` property is present in your project's `<PropertyGroup>` section. Use a human-readable, descriptive title:
29+
30+
```xml
31+
<PropertyGroup>
32+
<Title>Your Package Display Name</Title>
33+
<!-- Additional properties -->
34+
</PropertyGroup>
35+
```
36+
37+
### Step 3: Validate and Rebuild
38+
39+
Validate your project file for syntax errors and rebuild your project:
40+
41+
```bash
42+
dotnet build
43+
```
44+
45+
## Best Practices
46+
47+
- Use a clear, descriptive title that reflects the package's purpose
48+
- Keep the title concise (under 100 characters)
49+
- Use sentence case or PascalCase, consistent with your branding
50+
- Include the key functionality or domain in the title
51+
- Ensure the title is different from and more readable than the `<PackageId />`
52+
53+
## Example
54+
55+
```xml
56+
<Project Sdk="Microsoft.NET.Sdk">
57+
<PropertyGroup>
58+
<TargetFramework>net8.0</TargetFramework>
59+
<PackageId>NetEvolve.Defaults</PackageId>
60+
<Title>NetEvolve Build Defaults and Configuration</Title>
61+
<Description>Enterprise-grade build configuration and standards package</Description>
62+
</PropertyGroup>
63+
</Project>
64+
```
65+
66+
## See Also
67+
68+
- [NuGet Package Metadata Reference](https://docs.microsoft.com/en-us/nuget/reference/msbuild-targets)
69+
- [Creating Discoverable Packages](https://docs.microsoft.com/en-us/nuget/create-packages/creating-a-package)

0 commit comments

Comments
 (0)