Skip to content

Contributing to SERENDER

Thank you for your interest in contributing to SERENDER! This document provides guidelines and information for contributors and maintainers.

Table of Contents

Getting Started

Prerequisites

Before contributing, ensure you have the following installed:

  • .NET 9.0 SDK or higher
  • Docker Desktop (for infrastructure services)
  • Visual Studio 2022 or VS Code
  • Git
  • Node.js (for frontend contributions)

Development Environment Setup

  1. Fork the Repository 

    # Fork the repository on GitHub, then clone your fork
git clone [YOUR_FORK_URL]
cd [PROJECT_DIRECTORY]

  2. Set Up Upstream Remote 

    git remote add upstream [ORIGINAL_REPOSITORY_URL]

  3. Install Dependencies 

    # Restore .NET packages
dotnet restore

# Start infrastructure services
docker-compose up -d

  4. Verify Setup 

    # Run tests to ensure everything is working
dotnet test

How to Contribute

Types of Contributions

We welcome various types of contributions:

  • Bug Fixes: Help us fix issues and improve stability
  • Feature Development: Implement new features and enhancements
  • Documentation: Improve guides, API docs, and code comments
  • Testing: Add test coverage and improve existing tests
  • Performance: Optimize code and improve system performance
  • Security: Identify and fix security vulnerabilities
  • Refactoring: Improve code quality and maintainability

Finding Work

  • Check the Issues tab for open tickets
  • Look for issues labeled good first issue for beginners
  • Check issues labeled help wanted for priority items
  • Review the Project Roadmap for planned features

Development Workflow

Branch Strategy

We follow GitFlow branching model:

  • main: Production-ready code
  • develop: Integration branch for features
  • feature/*: New features and enhancements
  • bugfix/*: Bug fixes for develop branch
  • hotfix/*: Critical fixes for production
  • release/*: Release preparation

Branch Naming Convention

feature/[issue-number]-brief-description
bugfix/[issue-number]-brief-description
hotfix/[issue-number]-brief-description
release/v[version-number]

Examples: - feature/123-add-user-authentication - bugfix/456-fix-memory-leak - hotfix/789-security-patch

Working on a Feature

  1. Create a Branch 

    git checkout develop
git pull upstream develop
git checkout -b feature/123-your-feature-name

  2. Make Changes

  3. Write clean, well-documented code
  4. Follow coding standards
  5. Add/update tests as needed

  6. Update documentation if required

  7. Commit Changes 

    git add .
git commit -m "feat: add user authentication system

- Implement JWT token-based authentication
- Add login/logout endpoints
- Include password validation
- Add unit tests for auth service

Closes #123"

  8. Push and Create PR 

    git push origin feature/123-your-feature-name

Coding Standards

C# Guidelines

  • Follow Microsoft C# Coding Conventions
  • Use PascalCase for public members
  • Use camelCase for private members
  • Use meaningful names for variables and methods
  • Document public APIs with XML comments
  • Keep methods small and focused (max 20-30 lines)
  • Use async/await for asynchronous operations

Code Style

// Good
public async Task<UserDto> GetUserByIdAsync(int userId)
{
    if (userId <= 0)
        throw new ArgumentException("User ID must be positive", nameof(userId));

    var user = await _userRepository.GetByIdAsync(userId);
    return _mapper.Map<UserDto>(user);
}

// Bad
public UserDto GetUser(int id)
{
    var u = _repo.GetById(id);
    return new UserDto { Name = u.Name, Email = u.Email };
}

Project Structure

Follow Hexagonal Architecture principles:

├── Domain/              # Core business logic
├── Application/         # Use cases and business rules
├── Infrastructure/      # External concerns
│   ├── Persistence/     # Database implementation
│   ├── Bus/            # Message bus implementation
│   └── Rest/           # HTTP API implementation
├── Bootstrap/          # Application entry point
└── Test/               # Test projects

Testing Requirements

Test Coverage

  • Minimum 80% code coverage for new features
  • Unit tests for all business logic
  • Integration tests for API endpoints
  • Contract tests for external integrations

Test Categories

  1. Unit Tests 

    [Test]
public async Task GetUserById_ValidId_ReturnsUser()
{
    // Arrange
    var userId = 1;
    var expectedUser = new User { Id = userId, Name = "John Doe" };
    _mockRepository.Setup(r => r.GetByIdAsync(userId))
                  .ReturnsAsync(expectedUser);

    // Act
    var result = await _userService.GetUserByIdAsync(userId);

    // Assert
    Assert.That(result.Id, Is.EqualTo(userId));
    Assert.That(result.Name, Is.EqualTo("John Doe"));
}

  2. Integration Tests 

    [Test]
public async Task CreateUser_ValidData_ReturnsCreatedUser()
{
    // Arrange
    var newUser = new CreateUserRequest 
    { 
        Name = "Jane Doe", 
        Email = "jane@example.com" 
    };

    // Act
    var response = await _client.PostAsJsonAsync("/api/users", newUser);

    // Assert
    response.StatusCode.Should().Be(HttpStatusCode.Created);
    var user = await response.Content.ReadFromJsonAsync<UserDto>();
    user.Name.Should().Be("Jane Doe");
}

Running Tests

# Run all tests
dotnet test

# Run with coverage
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover

# Run specific test category
dotnet test --filter Category=Unit

Pull Request Process

Before Submitting

  • [ ] Ensure all tests pass
  • [ ] Code coverage meets requirements
  • [ ] Code follows style guidelines
  • [ ] Documentation is updated
  • [ ] Commit messages follow convention
  • [ ] Branch is up to date with target branch

PR Template

Use this template for your pull requests:

## Description
Brief description of the changes made.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Related Issues
Closes #[issue_number]

## Screenshots (if applicable)
Add screenshots to help explain your changes.

## Checklist
- [ ] My code follows the style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

Review Process

  1. Automated Checks: CI/CD pipeline runs automatically
  2. Code Review: At least one maintainer reviews the code
  3. Testing: QA team tests the changes (if applicable)
  4. Approval: Maintainer approves and merges the PR

Issue Reporting

Bug Reports

Use the bug report template:

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected behavior**
A clear and concise description of what you expected to happen.

**Screenshots**
If applicable, add screenshots to help explain your problem.

**Environment:**
 - OS: [e.g. Windows 10]
 - .NET Version: [e.g. 9.0]
 - Browser: [e.g. chrome, safari]
 - Version: [e.g. 22]

**Additional context**
Add any other context about the problem here.

Feature Requests

Use the feature request template:

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is.

**Describe the solution you'd like**
A clear and concise description of what you want to happen.

**Describe alternatives you've considered**
A clear and concise description of any alternative solutions or features you've considered.

**Additional context**
Add any other context or screenshots about the feature request here.

Maintainer Guidelines

Responsibilities

Code Maintainers: - Review and merge pull requests - Ensure code quality and standards - Provide feedback to contributors - Manage releases and versioning - Monitor project health

Community Maintainers: - Moderate discussions and issues - Help new contributors - Maintain documentation - Organize community events

Review Guidelines

  1. Code Quality
  2. Follows coding standards
  3. Has appropriate test coverage
  4. Documentation is updated

  5. No security vulnerabilities

  6. Functional Requirements

  7. Meets acceptance criteria
  8. Doesn't break existing functionality

  9. Performance impact is acceptable

  10. Review Checklist

  11. [ ] Code compiles without warnings
  12. [ ] Tests pass and coverage is adequate
  13. [ ] Code follows project conventions
  14. [ ] Documentation is updated
  15. [ ] Security considerations are addressed
  16. [ ] Performance impact is acceptable

Merge Requirements

  • 2 approvals required for major changes
  • 1 approval required for minor changes
  • All checks must pass before merging
  • Squash and merge for feature branches
  • Merge commit for release branches

Release Process

Versioning

We follow Semantic Versioning (SemVer): - MAJOR: Breaking changes - MINOR: New features (backward compatible) - PATCH: Bug fixes (backward compatible)

Release Steps

  1. Create Release Branch 

    git checkout develop
git pull origin develop
git checkout -b release/v1.2.0

  2. Update Version Numbers

  3. Update assembly versions
  4. Update package.json files

  5. Update CHANGELOG.md

  6. Final Testing

  7. Run full test suite
  8. Perform manual testing

  9. Security scan

  10. Create Release PR

  11. Create PR from release branch to main
  12. Get required approvals

  13. Merge to main

  14. Tag and Deploy 

    git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

  15. Update Develop 

    git checkout develop
git merge main
git push origin develop

Community

Communication Channels

  • GitHub Issues: Bug reports and feature requests
  • GitHub Discussions: General discussions and Q&A
  • Email: [MAINTAINER_EMAIL] for sensitive issues
  • Slack/Discord: [COMMUNITY_CHAT_LINK] for real-time chat

Getting Help

  • Check existing Issues and Discussions
  • Read the Documentation
  • Ask questions in Community Chat
  • Contact Maintainers directly for urgent issues

Recognition

We recognize contributors through: - Contributors file listing all contributors - Release notes mentioning significant contributions - Community highlights for outstanding contributions - Maintainer nominations for consistent contributors

Thank You!

Your contributions make this project better for everyone. We appreciate your time and effort in helping us build something amazing together!

For questions about this contributing guide, please open an issue or contact the maintainers.