🚀 Contributing to Nino

This comprehensive guide covers both contributing to the Nino project and understanding our modern CI/CD workflows.

🤝 How to Contribute

Quick Start for Contributors

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/Nino.git
cd Nino

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes following our guidelines below
Test your changes locally
Create a Pull Request

📋 Contribution Types

We welcome various types of contributions:

🐛 Bug fixes - Fix existing issues
✨ New features - Add functionality to Nino
📚 Documentation - Improve docs, examples, or guides
🎨 Code improvements - Refactoring, performance optimizations
🧪 Tests - Add or improve test coverage
🔧 Tooling - Improve build scripts, CI/CD, or development tools

🛠️ Development Setup

Prerequisites

.NET SDK 8.0+ (with 6.0 and 2.1 for multi-targeting)
Unity 2022.3.51f1 (for Unity development)
Git for version control
IDE (Visual Studio, VS Code, or JetBrains Rider)

Local Development

Build the solution:
```
cd src
dotnet restore
dotnet build
```
Run tests:
```
dotnet test
```
Run benchmarks (optional):
```
cd Nino.Benchmark
dotnet run -c Release
```

Unity Development

Copy .NET DLLs to Unity:

cp ./Nino.Core/bin/Debug/netstandard2.1/Nino.Core.dll ./Nino.Unity/Packages/com.jasonxudeveloper.nino/Runtime/
cp ./Nino.Generator/bin/Debug/netstandard2.1/Nino.Generator.dll ./Nino.Unity/Packages/com.jasonxudeveloper.nino/Runtime/

Open Unity project at src/Nino.Unity
Run Unity tests in the Test Runner window

📝 Coding Guidelines

Code Style

Follow existing patterns in the codebase
Use meaningful names for variables, methods, and classes
Write self-documenting code with clear intent
Add XML documentation for public APIs
Keep methods focused - single responsibility principle

Commit Message Format

We use Conventional Commits for better release notes:

type(scope): description

[optional body]

[optional footer]

Types:

feat: New features
fix: Bug fixes
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding/updating tests
chore: Maintenance tasks

Examples:

feat(serialization): add support for nullable reference types
fix(generator): resolve issue with nested generic types
docs(readme): update installation instructions
test(core): add unit tests for buffer writer

Testing Requirements

Add tests for new features
Update tests when modifying existing code
Ensure all tests pass before submitting PR
Test both .NET and Unity scenarios when applicable
Include edge cases and error conditions

🔄 Pull Request Process

Before Creating a PR

Sync with upstream:

git remote add upstream https://github.com/JasonXuDeveloper/Nino.git
git fetch upstream
git rebase upstream/main

Run full test suite:
```
dotnet test --verbosity normal
```
Check code builds in Release mode:
```
dotnet build -c Release
```

Creating the PR

Push your branch:

git push origin feature/your-feature-name

Create PR on GitHub with:
- Clear title describing the change
- Detailed description explaining what and why
- Link to issues if applicable
- Screenshots/examples for UI changes

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Other: ___________

## Testing
- [ ] Added/updated unit tests
- [ ] Tested on .NET
- [ ] Tested on Unity
- [ ] All tests pass

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated if needed
- [ ] No breaking changes (or clearly documented)

Review Process

Automated checks will run (CI/CD pipeline)
Maintainer review - expect feedback and iteration
Address feedback by pushing additional commits
Squash and merge once approved

🎯 CI/CD Pipeline

Our automated systems will:

✅ On Every PR/Push

Build .NET solution and Unity project
Run tests for both platforms
Check code quality and style
Run benchmarks on main branch
Report results in PR comments

🚫 PR Blocking Conditions

Build failures
Test failures
Merge conflicts
Missing required reviews

🏷️ Release Process (Maintainers)

For project maintainers managing releases:

📋 CI/CD Overview

Our automated workflow system provides:

✅ Build and test for all commits - CI runs on every push and PR
✅ Modern semantic versioning - Support for stable and pre-releases (alpha, beta, rc)
✅ Tag-based releases - No more commit message parsing
✅ Automatic release notes - Generated from commit history
✅ GitHub Actions best practices - Latest actions, caching, concurrency control
✅ Integrated benchmarks - Automatic performance reports on releases
✅ Environment protection - Safe deployment to NuGet

This ensures every contribution is automatically tested and validated.

🔄 Workflows

1. CI - Build and Test (`ci.yml`)

Triggers: Push/PR to main or develop branches

Features:

Builds and tests both .NET and Unity projects
Runs on every commit for early feedback
Caches dependencies for faster builds
Uploads test results and coverage
Runs benchmarks on main branch pushes (but doesn't update releases)

2. Release (`release.yml`)

Triggers: Push of version tags (v*)

Features:

Validates semantic version format with security checks
Pre-release support: alpha, beta, rc with proper NuGet/Unity handling
Smart version management: Different formats for NuGet vs Unity UPM
Auto-generated release notes: Includes PR titles, contributors, and installation instructions
Builds, tests, and publishes to NuGet with retry logic
Unity UPM handling: Stable releases update main branch, pre-releases create separate branches
Environment protection and comprehensive error handling

3. Benchmark and Performance Report (`report.yml`)

Triggers:

Release published events
Manual dispatch
Called from release workflow

Features:

Runs comprehensive benchmarks
Updates release notes with performance data
Stores benchmark artifacts
Prevents duplicate benchmark runs

🏷️ Creating Releases (Maintainers Only)

🔄 Complete Release Process

When you create a release tag, the CI automatically:

✅ Validates the tag format and version
🔍 Verifies CI passed for the commit (waits if still running)
📝 Updates all version files (Version.cs, .csproj, package.json)
🏷️ Moves the tag to point to the updated commit
📚 Copies Release DLLs to Unity package folder
🌱 Creates appropriate branches (main for stable, release/* for pre-releases)
📦 Publishes to NuGet with proper versioning
📊 Runs benchmarks and updates release notes
🧹 Cleans up pre-release branches after successful completion

Easy Way: Use the Helper Script

# Stable release
./create-release.sh 1.2.3

# Pre-releases (all supported)
./create-release.sh 1.2.3 alpha  # Creates v1.2.3-alpha.1
./create-release.sh 1.2.3 beta   # Creates v1.2.3-beta.1  
./create-release.sh 1.2.3 rc     # Creates v1.2.3-rc.1

# Sequential releases auto-increment
./create-release.sh 1.2.3 alpha  # Creates v1.2.3-alpha.2 (if alpha.1 exists)
./create-release.sh 1.2.3 beta   # Creates v1.2.3-beta.2 (if beta.1 exists)

⚠️ Important: You only create the tag - CI handles everything else automatically!

🔍 Smart CI Verification

The release workflow intelligently handles CI status:

✅ CI Already Passed: Release continues immediately
⏳ CI Still Running: Waits up to 30 minutes for completion
❌ CI Failed: Blocks release with clear error message
⚠️ No CI Found: Warns but continues (for edge cases)

This ensures every release is from tested code while avoiding redundant test runs.

🏷️ Smart Tag Management

Important: The release workflow automatically moves your tag to ensure consistency:

You create tag pointing to commit A (your latest code)
CI updates versions and creates commit B (with version files + DLLs)
CI moves your tag to point to commit B (the actual release)
Release artifacts are built from commit B (correct versions)

This ensures the release tag always points to the exact commit that becomes the release, including all version updates and Unity DLLs.

Manual Way: Git Tags

# Stable release
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

# Pre-release
git tag -a v1.2.3-beta.1 -m "Release v1.2.3-beta.1"
git push origin v1.2.3-beta.1

📊 Version Management

🎯 Smart Version Handling

The workflow automatically handles different versioning requirements:

Stable Releases (v1.2.3):

src/Version.cs - Assembly versions: 1.2.3
.csproj files - NuGet versions: 1.2.3
package.json - Unity UPM: 1.2.3
Unity packages pushed to main branch

Pre-releases (v1.2.3-beta.1):

src/Version.cs - Assembly versions: 1.2.3 (base version)
.csproj files - NuGet versions: 1.2.3-beta.1 (full semantic version)
package.json - Unity UPM: 1.2.3-preview.1 (Unity-compatible format)
Unity packages pushed to release/1.2.3-beta.1 branch (not main)

📄 What CI Updates Automatically:

Version Files:

src/Version.cs - Assembly versions
src/Nino.Core/Nino.Core.csproj - Core package version
src/Nino/Nino.csproj - Main package version
src/Nino.Generator/Nino.Generator.csproj - Generator package version
src/Nino.Unity/Packages/com.jasonxudeveloper.nino/package.json - Unity package version

Unity Package DLLs:

Copies Nino.Core.dll (Release build) to Unity Runtime folder
Copies Nino.Generator.dll (Release build) to Unity Runtime folder
Commits these to appropriate branch (main for stable, release/* for pre-releases)

NuGet Packages:

Builds and publishes all packages with correct versioning
Handles pre-release suffixes properly (1.2.3-beta.1)

🔒 Security and Environment Protection

Production environment protection for NuGet publishing
Secrets management for Unity license and NuGet API keys
Concurrency control to prevent parallel releases
Validation steps before any deployment

📈 Monitoring and Observability

GitHub Actions summaries with release status
Artifact uploads for test results and benchmarks
Release notifications in workflow outputs
Performance tracking via benchmark reports

🔧 Configuration

Required Secrets

UNITY_EMAIL - Unity license email
UNITY_PASSWORD - Unity license password
UNITY_SERIAL - Unity license serial
MYTOKEN - NuGet API key

Optional Variables

DOTNET_VERSION - .NET version override (defaults to 8.0.x)

Environment Protection (Recommended)

Set up environment protection for production and nuget-production environments in your repository settings for additional security.

🎯 Complete Release Type Matrix

Type	Command	Git Tag	NuGet	Unity UPM	Branch	Use Case
Stable	`./create-release.sh 1.2.3`	`v1.2.3`	`1.2.3`	`1.2.3`	`main`	Production ready
Alpha	`./create-release.sh 1.2.3 alpha`	`v1.2.3-alpha.1`	`1.2.3-alpha.1`	`1.2.3-preview.1`	`release/1.2.3-alpha.1`	Early development
Beta	`./create-release.sh 1.2.3 beta`	`v1.2.3-beta.1`	`1.2.3-beta.1`	`1.2.3-preview.1`	`release/1.2.3-beta.1`	Feature complete
RC	`./create-release.sh 1.2.3 rc`	`v1.2.3-rc.1`	`1.2.3-rc.1`	`1.2.3-preview.1`	`release/1.2.3-rc.1`	Final testing

🔄 Sequential Numbering

Multiple pre-releases auto-increment: alpha.1, alpha.2, beta.1, rc.1, etc.
Each type maintains its own counter
Example flow: v1.2.3-alpha.1 → v1.2.3-alpha.2 → v1.2.3-beta.1 → v1.2.3-rc.1 → v1.2.3

❓ FAQ: Do I Need to Manually Copy DLLs or Update package.json?

✅ No! The release workflow automatically:

Builds Release configuration DLLs
Copies them to Unity package Runtime folder
Updates package.json with correct version format
Commits changes to the appropriate branch
Publishes to NuGet

You only need to create the version tag - everything else is automated!

🎮 Unity UPM & Branch Strategy

❓ Do I need to create branches manually? ✅ No! The CI automatically handles all branching:

Stable releases (v1.2.3): CI updates main branch directly
Pre-releases (v1.2.3-beta.1): CI automatically creates release/1.2.3-beta.1 branches
You only create tags - CI handles the rest

Unity UPM Compatibility:

Unity doesn't support semantic pre-release format (-alpha.1, -beta.1)
All pre-releases use Unity's -preview.N format for compatibility
Unity Package Manager auto-detects updates on these branches

💡 Best Practices

For Contributors

Start small - Begin with bug fixes or documentation
Discuss big changes - Open an issue before major features
Follow conventions - Use existing patterns and styles
Write tests - Ensure your changes are well-tested
Document changes - Update docs for new features
Be responsive - Address review feedback promptly

For Maintainers

Follow the release lifecycle: alpha → beta → rc → stable
Use the helper script for consistent tag creation
Monitor workflow runs in the Actions tab
Check benchmark results in release notes
Keep commit messages descriptive - They become release notes
Use conventional commits for better auto-generated release notes

🌟 Recognition

Contributors are recognized in:

Release notes - Auto-generated contributor lists
GitHub contributors - Visible on the repository
Special mentions - For significant contributions

💬 Getting Help

GitHub Issues - For bugs and feature requests
GitHub Discussions - For questions and general discussion
Pull Request comments - For code-specific questions
Review workflow logs - For CI/CD issues

🔧 CI/CD Technical Documentation

The following sections detail our automated systems for maintainers and advanced contributors.

🆘 Troubleshooting

Common Issues

Tag already exists: Delete the tag locally and remotely, then recreate
```
git tag -d v1.2.3
git push origin :refs/tags/v1.2.3
```
Unity tests failing: Check Unity license secrets are properly configured
NuGet publish failing: Verify MYTOKEN secret and package versions
Benchmark not running: Check if it was already run for this release

Getting Help

Check the workflow run logs in GitHub Actions
Review the job summaries for detailed status
Validate your git tags match semantic versioning format
Ensure all required secrets are configured

🤝 Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment:

Be respectful - Treat everyone with respect and kindness
Be constructive - Provide helpful feedback and suggestions
Be patient - Help others learn and grow
Be inclusive - Welcome contributors from all backgrounds

Issue Reporting

When reporting bugs:

Search existing issues first
Use issue templates when available
Provide reproduction steps
Include environment details (.NET version, Unity version, OS)
Attach logs/screenshots when relevant

Feature Requests

Check roadmap and existing issues
Explain the use case clearly
Describe expected behavior
Consider backwards compatibility
Be open to discussion and alternatives

📚 Additional Resources

Nino Documentation - Complete usage guide
GitHub Repository - Source code and issues
Release Notes - What's new in each version
Benchmarks - Performance comparisons

Thank you for contributing to Nino! 🎉 Your contributions help make high-performance serialization accessible to everyone.

FilesExpand file tree

WORKFLOW.md

Latest commit

History

WORKFLOW.md

File metadata and controls

🚀 Contributing to Nino

🤝 How to Contribute

Quick Start for Contributors

📋 Contribution Types

🛠️ Development Setup

Prerequisites

Local Development

Unity Development

📝 Coding Guidelines

Code Style

Commit Message Format

Testing Requirements

🔄 Pull Request Process

Before Creating a PR

Creating the PR

PR Template

Review Process

🎯 CI/CD Pipeline

✅ On Every PR/Push

🚫 PR Blocking Conditions

🏷️ Release Process (Maintainers)

📋 CI/CD Overview

🔄 Workflows

1. CI - Build and Test (ci.yml)

2. Release (release.yml)

3. Benchmark and Performance Report (report.yml)

🏷️ Creating Releases (Maintainers Only)

🔄 Complete Release Process

Easy Way: Use the Helper Script

🔍 Smart CI Verification

🏷️ Smart Tag Management

Manual Way: Git Tags

📊 Version Management

🎯 Smart Version Handling

📄 What CI Updates Automatically:

🔒 Security and Environment Protection

📈 Monitoring and Observability

🔧 Configuration

Required Secrets

Optional Variables

Environment Protection (Recommended)

🎯 Complete Release Type Matrix

🔄 Sequential Numbering

❓ FAQ: Do I Need to Manually Copy DLLs or Update package.json?

🎮 Unity UPM & Branch Strategy

💡 Best Practices

For Contributors

For Maintainers

🌟 Recognition

💬 Getting Help

🔧 CI/CD Technical Documentation

🆘 Troubleshooting

Common Issues

Getting Help

🤝 Community Guidelines

Code of Conduct

Issue Reporting

Feature Requests

📚 Additional Resources

1. CI - Build and Test (`ci.yml`)

2. Release (`release.yml`)

3. Benchmark and Performance Report (`report.yml`)