169 lines
4.2 KiB
Markdown
169 lines
4.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cd src
|
|
dotnet build MaksIT.Core.sln
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
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](https://semver.org/):
|
|
|
|
- **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):
|
|
```powershell
|
|
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:
|
|
```bash
|
|
git add -A
|
|
git commit -m "(chore): release v1.x.x"
|
|
```
|
|
|
|
4. **Create version tag**:
|
|
```bash
|
|
git tag v1.x.x
|
|
```
|
|
|
|
5. **Run release script**:
|
|
```powershell
|
|
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.
|