Skip to content

Contributing Libraries

This document explains how to add or change shared libraries (ConnectSoft.Extensions.* etc.). It is written for engineers who want to contribute to ConnectSoft's shared library ecosystem.

ConnectSoft libraries provide reusable functionality across templates and generated services. Contributions must follow API design guidelines, versioning rules, and quality standards.

Important

Libraries must be small, focused, and reusable. No business-specific logic should be in generic libraries. All libraries must include good defaults and be override-able via options.

When to Create or Change a Library

Create a New Library When:

  • Reusable Functionality - Functionality is needed across multiple services
  • Cross-Cutting Concern - Common cross-cutting concern (logging, HTTP, messaging)
  • Standard Pattern - Standard pattern that should be consistent
  • Platform Integration - Integration with ConnectSoft platforms

Change an Existing Library When:

  • Bug Fixes - Fixing bugs or issues
  • New Features - Adding backward-compatible features
  • Breaking Changes - Making breaking changes (requires ADR and major version bump)

Design and API Guidelines

Small, Focused Responsibility

  • Single Responsibility - Each library should have a single, focused responsibility
  • No Business Logic - No business-specific logic in generic libraries
  • Composable - Libraries should be composable and work together

Good Defaults, Override-able via Options

  • Sensible Defaults - Provide sensible defaults for common use cases
  • Options Pattern - Use options pattern for configuration
  • Validation - Validate options and provide clear error messages

Tip

Options Pattern: Use Microsoft.Extensions.Options pattern for configuration. Provide good defaults, validate options, and make them override-able. This makes libraries easy to use while allowing customization.

API Design Principles

  • Consistent Naming - Use consistent naming conventions
  • Async by Default - Prefer async APIs for I/O operations
  • Dependency Injection - Support dependency injection
  • Logging - Include structured logging
  • Error Handling - Provide clear error messages

Versioning and Compatibility

Semantic Versioning

Follow Semantic Versioning (SemVer):

  • MAJOR - Breaking changes (incompatible API changes)
  • MINOR - Backward-compatible features (new functionality)
  • PATCH - Backward-compatible bug fixes

Backward Compatibility Expectations

  • Minor Versions - Must be backward compatible
  • Patch Versions - Must be backward compatible
  • Major Versions - Breaking changes require major version bump

Deprecation Warnings

  • Advance Notice - Deprecate APIs with advance notice (at least one minor version)
  • Obsolete Attributes - Use [Obsolete] attributes for deprecated APIs
  • Migration Guides - Provide migration guides for deprecated APIs

Testing and Quality Gates

Unit Tests

  • Coverage - Minimum 80% code coverage
  • Edge Cases - Test edge cases and error conditions
  • Mocking - Use mocks for external dependencies

Integration Tests

  • Real Scenarios - Test real integration scenarios
  • End-to-End - Test end-to-end flows where relevant
  • Performance - Test performance characteristics

Quality Requirements

  • Logging - Include structured logging
  • Error Messages - Provide clear, actionable error messages
  • Documentation - Document APIs and usage
  • Examples - Provide usage examples

Publishing and Consumption

Publishing Process

  1. Build - Build library with tests passing
  2. Version - Update version number (SemVer)
  3. Package - Create NuGet package
  4. Publish - Publish to Azure DevOps Artifacts
  5. Documentation - Update library documentation

Consumption

  • NuGet Reference - Libraries are consumed via NuGet packages
  • Template Integration - Templates reference libraries via NuGet
  • Version Pinning - Pin library versions in templates
  • Update Process - Update libraries through controlled process

Version Management

  • Template Versions - Templates pin library versions
  • Update Strategy - Update libraries regularly for security and features
  • Breaking Changes - Coordinate breaking changes across templates