Skip to content

Latest commit

 

History

History
204 lines (146 loc) · 5.62 KB

CONTRIBUTING.md

File metadata and controls

204 lines (146 loc) · 5.62 KB

Contributing to EasilyNET

Thank you for your interest in contributing to EasilyNET! We welcome contributions from the community. This document provides guidelines and information to help you get started.

Table of Contents

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to dygood@outlook.com.

Getting Started

Prerequisites

  • .NET 10 SDK (latest version recommended)
  • Git
  • Optional: Docker for running services like MongoDB, RabbitMQ, etc.

Fork and Clone

  1. Fork the repository on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/EasilyNET.git
cd EasilyNET
  3. Add the upstream remote: 
    git remote add upstream https://github.com/joesdu/EasilyNET.git

Branching

  • Create a new branch for your changes: 
    git checkout -b feature/your-feature-name
  • Use descriptive branch names (e.g., feature/add-new-encryption-method, fix/bug-in-mongo-driver).

Development Environment Setup

  1. Ensure you have the latest .NET 10 SDK installed.

  2. Restore dependencies:

    dotnet restore

  3. Build the solution:

    dotnet build

  4. For testing with external services, start the required containers:

    # For MongoDB replica set
docker compose -f docker-compose.mongo.rs.yml up -d

# For basic services (Garnet, RabbitMQ, Aspire Dashboard)
docker compose -f docker-compose.basic.service.yml up -d

Running the Sample Application

The sample application is located in sample/WebApi.Test.Unit/. To run it:

cd sample/WebApi.Test.Unit
dotnet run

Project Structure

  • src/: Source code for all packages
    • EasilyNET.Core/: Core utilities and extensions
    • EasilyNET.WebCore/: Web API related components
    • EasilyNET.AutoDependencyInjection/: Dependency injection framework
    • EasilyNET.RabbitBus.AspNetCore/: RabbitMQ message bus for ASP.NET Core
    • EasilyNET.Mongo.AspNetCore/: MongoDB integration for ASP.NET Core
    • EasilyNET.Security/: Security and encryption utilities
  • sample/: Sample applications and usage examples
  • test/: Unit tests and benchmarks
  • docs/: Documentation for individual packages

Coding Standards

General Guidelines

  • Follow the existing code style in the project.
  • Use meaningful variable and method names.
  • Add XML documentation comments for public APIs.
  • Keep methods small and focused on a single responsibility.

C# Specific

  • Use the latest C# features where appropriate (project targets .NET 10 and C# preview features).
  • Prefer async/await for asynchronous operations.
  • Use pattern matching and modern language features.
  • Follow the Microsoft C# Coding Conventions.

Commit Messages

  • Use clear, descriptive commit messages.
  • Start with a verb (e.g., "Add", "Fix", "Update", "Refactor").
  • Keep the first line under 50 characters.
  • Add more details in the body if needed.

Example:

Add support for DateOnly and TimeOnly in MongoDB serialization

- Serialize DateOnly as string in ISO format
- Serialize TimeOnly as long (ticks)
- Add unit tests for new serialization logic

Testing

Running Tests

Run all tests:

dotnet test

Run tests for a specific project:

dotnet test test/EasilyNET.Test.Unit/EasilyNET.Test.Unit.csproj

Writing Tests

  • Write unit tests for new features and bug fixes.
  • Use xUnit as the testing framework (follow existing patterns).
  • Aim for good test coverage.
  • Place tests in the appropriate test/ directory.

Benchmarks

For performance-critical code, add benchmarks in test/EasilyNET.Core.Benchmark/.

Submitting Changes

  1. Ensure your code builds and all tests pass:

    dotnet build
dotnet test

  2. Update documentation if needed (README files in src/ directories).

  3. Commit your changes:

    git add .
git commit -m "Your descriptive commit message"

  4. Push to your fork:

    git push origin feature/your-feature-name

  5. Create a Pull Request:

    • Go to the original repository on GitHub.
    • Click "New Pull Request".
    • Select your branch and provide a clear description of your changes.
    • Reference any related issues.

Pull Request Guidelines

  • Provide a clear title and description.
  • Include screenshots or examples for UI changes.
  • Keep PRs focused on a single feature or fix.
  • Ensure CI checks pass.
  • Be responsive to feedback and make requested changes.

Reporting Issues

  • Use GitHub Issues to report bugs or request features.
  • Provide detailed steps to reproduce bugs.
  • Include relevant environment information (.NET version, OS, etc.).
  • Check existing issues before creating new ones.

License

By contributing to this project, you agree that your contributions will be licensed under the same MIT License that covers the project.

Thank you for contributing to EasilyNET! Your efforts help make this project better for everyone.