maksit-core/CONTRIBUTING.md

Contributing to MaksIT.Core

Thank you for your interest in contributing to MaksIT.Core! This document provides guidelines for contributing to the project.

Getting Started

1. Fork the repository
2. Clone your fork locally
3. Create a new branch for your changes
4. Make your changes
5. Submit a pull request

Development Setup

Prerequisites

• .NET10 SDK or later
• Git

Building the Project

cd src
dotnet build MaksIT.Core.sln

Running Tests

cd src
dotnet test MaksIT.Core.Tests

Commit Message Format

This project uses the following commit message format:

(type): description

Commit Types

Type	Description
(feature):	New feature or enhancement
(bugfix):	Bug fix
(refactor):	Code refactoring without functional changes
(chore):	Maintenance tasks (dependencies, CI, documentation)

Examples

(feature): add support for custom JWT claims
(bugfix): fix multithreading issue in file logger
(refactor): simplify expression extension methods
(chore): update copyright year to 2026

Guidelines

• Use lowercase for the description
• Keep the description concise but descriptive
• No period at the end of the description

Code Style

• Follow standard C# naming conventions
• Use XML documentation comments for public APIs
• Keep methods focused and single-purpose
• Write unit tests for new functionality

Pull Request Process

1. Ensure all tests pass
2. Update documentation if needed
3. Update CHANGELOG.md with your changes under the appropriate version section
4. Submit your pull request against the main branch

Versioning

This project follows Semantic Versioning:

• MAJOR - Breaking changes
• MINOR - New features (backward compatible)
• PATCH - Bug fixes (backward compatible)

Release Process

The release process is automated via PowerShell scripts in the src/ directory.

Prerequisites

• Docker Desktop running (for Linux tests)
• GitHub CLI (gh) authenticated
• NuGet API key in NUGET_API_KEY environment variable
• GitHub token in GITHUB_MAKS_IT_COM environment variable

Release Workflow

1. Update version in MaksIT.Core/MaksIT.Core.csproj

2. Generate changelog (uses AI with Ollama if available):

   cd src
   .\Generate-Changelog.ps1        # Updates CHANGELOG.md and LICENSE.md year
   .\Generate-Changelog.ps1 -DryRun  # Preview without changes
   

3. Review and commit all changes:

   git add -A
   git commit -m "(chore): release v1.x.x"
   

4. Create version tag:

   git tag v1.x.x
   

5. Run release script:

   cd src
   .\Release-NuGetPackage.ps1        # Full release
   .\Release-NuGetPackage.ps1 -DryRun  # Test without publishing
   

How Release Works

The release script:

1. Reads latest version from CHANGELOG.md
2. Finds the commit with the matching version tag (e.g., v1.2.3)
3. Checks if already released on NuGet.org - skips if yes
4. Builds and tests the tagged commit
5. Publishes to NuGet and GitHub

You can run the release script from any branch or commit - it will always release the commit that has the version tag matching the latest changelog entry.

Release Script Validation

• Version source: Reads latest version from CHANGELOG.md
• Tag required: Must have a tag matching the changelog version
• Branch validation: Tag must be on configured branch (default: main, set in scriptsettings.json)
• Already released: Skips if version exists on NuGet.org
• Clean working directory: No uncommitted changes allowed

What the Release Script Does

1. Validates prerequisites and environment
2. Runs security vulnerability scan
3. Builds and tests on Windows
4. Builds and tests on Linux (via Docker)
5. Analyzes code coverage
6. Creates NuGet package
7. Pushes to NuGet.org
8. Creates GitHub release with assets

Re-releasing

To re-release the same version (e.g., to fix release assets):

• Keep the same tag on the same commit
• Run the release script again
• It will delete the existing GitHub release and recreate it

License

By contributing, you agree that your contributions will be licensed under the MIT License.