chore: add central build management and reorganize project structure

[gurolg]

chore: add central build management and reorganize project structure

This commit introduces significant improvements to the project's build
infrastructure and organization, following .NET library best practices
(similar to Azure SDK, .NET Runtime, and Roslyn repositories).

Central Package Management

Added src/Directory.Packages.props:

• Enables ManagePackageVersionsCentrally for all src projects
• Centralizes all package versions in one location
• Introduces MicrosoftAgentsAIVersion variable for coordinated updates
• All PackageReference elements in csproj files now omit Version attribute
• Includes Microsoft.SourceLink.GitHub for source debugging support

Benefits:

• Single source of truth for package versions
• Prevents version drift across projects
• Simplifies dependency updates
• Reduces merge conflicts

Shared Build Configuration

Added src/Directory.Build.props:

• Defines common build properties (TargetFramework=net8.0, Nullable=enable,
  ImplicitUsings=enable, LangVersion=latest)
• Enforces code quality (TreatWarningsAsErrors=true, EnableNETAnalyzers=true,
  AnalysisLevel=latest)
• Sets IsPackable=false by default, libraries explicitly opt-in
• Conditional configuration for test projects

Added src/Directory.Build.targets:

• Standardizes packaging for all libraries (SymbolPackageFormat=snupkg,
  IncludeSymbols=true)
• Enables source embedding (EmbedUntrackedSources=true)
• Configures repository metadata (PublishRepositoryUrl=true, RepositoryType=git)
• Enables deterministic builds (Deterministic=true, ContinuousIntegrationBuild=true)
• Adds package validation (EnablePackageValidation=true) for API compatibility checks
• Integrates Microsoft.SourceLink.GitHub for symbol packages

Project File Cleanup

Updated all library .csproj files (10 projects):

• Removed duplicated properties now in Directory.Build.props:
  • TargetFramework, ImplicitUsings, Nullable
  • GeneratePackageOnBuild, WarningsAsErrors, TreatWarningsAsErrors
• Removed Version attributes from all PackageReference elements
• Kept only project-specific properties (Description, custom settings)
• Maintained Import of nuget-package.props and ProjectReference elements

Updated src/nuget-package.props:

• Removed properties migrated to Directory.Build.targets:
  • IsPackable, PublishRepositoryUrl, IncludeSymbols
  • EmbedUntrackedSources, DebugType, Deterministic, ContinuousIntegrationBuild
• Kept NuGet-specific metadata (PackageVersion, Authors, License, Tags, Icon, README)

Test Project Updates

Updated src/AgentFrameworkToolkit.Tests/AgentFrameworkToolkit.Tests.csproj:

• Changed TargetFramework from net10.0 to net8.0 (align with LTS)
• Removed ImplicitUsings and Nullable (now inherited from Directory.Build.props)
• Removed Version attributes from test package references

Documentation & Contributor Experience

Added CONTRIBUTING.md:

• Comprehensive guide for contributors
• Repository structure explanation
• Prerequisites and getting started instructions
• Development workflow (central package management, build configuration)
• Guidelines for adding new provider packages
• Coding standards and conventions
• Pull request guidelines
• Testing practices
• Release process documentation

Updated README.md:

• Added link to CONTRIBUTING.md for developer guidance
• Maintains focus on package users (NuGet audience)

Updated AgentFrameworkToolkit.slnx:

• Added CONTRIBUTING.md to /Solution Items/ folder
• Organized solution items logically

Build Verification

All changes verified with:

• dotnet restore (successful with central package management)
• dotnet build --configuration Release (0 errors, 0 warnings)
• dotnet test (4/4 tests passed on net8.0)
• dotnet pack (20 .nupkg + 10 .snupkg generated successfully)

Breaking Changes

None. All changes are internal to the build system and do not affect:

• Public APIs
• Package consumers
• Runtime behavior
• Package metadata (version, authors, license, etc.)

Rationale

These changes establish a solid foundation for the repository:

1. Reduces maintenance burden by centralizing configuration
2. Enforces consistency across all packages
3. Improves developer experience with clear contribution guidelines
4. Aligns with .NET ecosystem best practices
5. Enables advanced features (SourceLink, package validation)
6. Prepares the repository for future growth

[rwjdk]

Hi @gurolg ... Thank you for the PR 👍👍👍

I'm quite busy rest of this week (including the weekend), so I might first have time to look/approve this next week.

[rwjdk]

Awesome work... Much appreciated (and learned a lot from the changes) 💪🙌

[gurolg]

You’re very welcome, Rasmus — thank you!
I’ve learned a lot from your videos.
Happy holidays! 🎄😊