Skip to content

Latest commit

 

History

History
140 lines (96 loc) · 3.55 KB

CONTRIBUTING.md

File metadata and controls

140 lines (96 loc) · 3.55 KB

Contributing to Community.Microsoft.Extensions.Caching.PostgreSql

Thank you for your interest in contributing to our PostgreSQL Distributed Cache implementation for .NET! This document provides guidelines and standards for contributing to the project.

Development Environment Setup

  1. Install the following prerequisites:

    • .NET SDK (versions 6.0, 8.0, and 9.0)
    • PostgreSQL 11+
    • Your preferred IDE (Visual Studio, VS Code, Rider, etc.)

  2. Clone the repository:

git clone https://github.com/leonibr/community-extensions-cache-postgres.git

Code Standards

Project Structure

  • Source code goes in Extensions.Caching.PostgreSql/
  • Sample projects in PostgreSqlCacheSample/ and WebSample/
  • Tests should be placed in a corresponding test project

Coding Conventions

  1. Language Version

    • Use C# 11 features (<LangVersion>11</LangVersion>)
    • Target multiple frameworks: net6.0, net8.0, and net9.0

  2. Naming Conventions

    • Use PascalCase for public members and types
    • Use camelCase for private fields
    • Prefix private fields with underscore (_)
    private readonly ILogger<DatabaseOperations> _logger;

  3. String Interpolation

    • Use raw string literals for SQL queries
    public string CreateSchemaAndTableSql =>
    $"""
    CREATE SCHEMA IF NOT EXISTS "{_schemaName}";
    // ...
    """;

  4. Async/Await

    • Always provide async versions of methods with CancellationToken support
    • Use the Async suffix for async methods
    public async Task DeleteCacheItemAsync(string key, CancellationToken cancellationToken)

  5. Dependency Injection

    • Use constructor injection
    • Mark dependencies as readonly when possible
    private readonly ILogger<DatabaseOperations> _logger;

  6. Error Handling

    • Use structured logging with ILogger
    • Validate input parameters
    • Throw appropriate exceptions with meaningful messages

Documentation

  1. XML Comments

    • Add XML comments for public APIs
    • Include parameter descriptions and examples where appropriate
    /// <summary>
/// The factory to create a NpgsqlDataSource instance.
/// Either <see cref="DataSourceFactory"/> or <see cref="ConnectionString"/> should be set.
/// </summary>
public Func<NpgsqlDataSource> DataSourceFactory { get; set; }

  2. README Updates

    • Update README.md when adding new features
    • Include usage examples for new functionality

Testing (optional for now)

  1. Write unit tests for new functionality
  2. Ensure all tests pass before submitting PR
  3. Include integration tests for database operations

Pull Request Process

  1. Create a feature branch from master
  2. Make your changes following the coding standards
  3. Update documentation as needed
  4. Run all tests (if any)
  5. Submit a pull request with:
    • Clear description of changes
    • Any related issue numbers
    • Breaking changes noted
    • Documentation updates

Dependencies

Keep dependencies up to date with the latest stable versions:

Release Process

  1. Version numbers follow SemVer

  2. Update version in .csproj:

    <Version>4.0.0</Version>

  3. Update PackageReleaseNotes in .csproj

  4. Document breaking changes in README.md

Questions or Problems?

  • Open an issue for bugs or feature requests
  • For questions, use GitHub Discussions
  • For security issues, please see SECURITY.md

License

This project is licensed under the MIT License - see the LICENSE file for details.