Contributing to SharpIppNext

First off, thank you for considering contributing to SharpIppNext! It's people like you who make the open-source community such an amazing place to learn, inspire, and create.

Getting Started

To contribute to this project, you will need:

  • .NET SDK 10.0 or later.
  • A C# IDE (e.g., Visual Studio 2026 or VS Code).

Clone the Repository

It is recommended to create a fork of the repository (fork button in GitHub) and clone your fork. Alternatively, you can clone the main repository directly:

git clone https://github.com/danielklecha/SharpIppNext.git
cd SharpIppNext

Repository Structure

The solution is divided into the following projects:

  • SharpIpp: The core IPP protocol library, containing client (ISharpIppClient) and server (ISharpIppServer) implementations, models, and protocol serialization (targets netstandard2.0 and net10.0).
  • SharpIpp.Generators: Roslyn incremental source generators (IIncrementalGenerator) that produce compile-time object mapping (SimpleMapper) and validation routines, ensuring zero-reflection NativeAOT and trimming compatibility (targets netstandard2.0).
  • SharpIpp.Generators.Tests.Unit: Unit tests for verifying source generator output and behavior.
  • SharpIpp.Tests.Unit & SharpIpp.Tests.Integration: Comprehensive test suites for protocol serialization, mapping symmetry, and end-to-end client/server workflows.
  • SharpIpp.Samples.*: Sample applications demonstrating standard usage, NativeAOT deployment, and UWP integrations.

How to Contribute

Building the Project

You can build the entire solution using the .NET CLI:

dotnet build --configuration Release

Working with Source Generators (SharpIpp.Generators)

If you are modifying or extending attributes ([IppRequest], [IppResponse], [IppAttribute]) or mapping logic:

  • Target Framework: SharpIpp.Generators targets netstandard2.0 as required by the Roslyn compiler infrastructure.
  • Testing Generators: When changing generator logic, add or update tests in SharpIpp.Generators.Tests.Unit.
  • IDE Caching: Visual Studio and IDEs may cache generator outputs in background compiler processes. If generated code does not appear to reflect edits immediately, rebuild the solution or restart the IDE Roslyn language server.

Running Tests

We use MSTest V2 for testing. To run all tests and collect coverage information, use:

dotnet test --configuration Release /p:CollectCoverage=true /p:CoverletOutput=TestResults/ /p:CoverletOutputFormat="opencover,lcov"

Please ensure all tests pass before submitting a pull request.

Code Coverage

When running tests with the coverage flags as shown above, coverage reports are generated in the TestResults/ directory.

  • Local Review: You can use tools like ReportGenerator to convert the opencover or lcov reports into a human-readable HTML format for local review.
  • CI/CD Integration: Our CI pipeline automatically publishes coverage reports to Coveralls for every push and pull request.

Coding Standards

  • Follow standard C# naming conventions and best practices.
  • Adhere to the rules defined in the .editorconfig file.
  • Keep methods focused and classes loosely coupled.

Pull Request Process

  1. Create a Branch: Use a descriptive name for your branch (e.g., feature/add-cups-operation or bugfix/fix-serialization-error).
  2. Commit Changes: Make atomic commits with clear, descriptive messages.
  3. Draft Pull Request: If your work is still in progress, open a Draft Pull Request to get early feedback.
  4. Final Pull Request: Ensure your branch is up-to-date with master and all CI checks pass.
  5. Review: At least one maintainer will review your PR before merging.

Maintainer Notes: Releasing Maintenance Branches

When creating a maintenance branch for an older version (e.g., creating branch v3.x after v4 is already released):

  1. Modify Release Workflow: In the new maintenance branch, update the .github/workflows/create-release.yml file so that new releases do not overwrite the "Latest" tag on GitHub:
    # Change this:
    # gh release create "$tag" --generate-notes
    # To this:
    gh release create "$tag" --generate-notes --latest=false
    
  2. Push Tags: When you push a new release tag from this branch (e.g., v3.1.2), the GitHub Action will build and publish it to NuGet, but it will not mark it as the latest release on GitHub.

Reporting Issues

If you find a bug or have a feature request, please search the existing issues before opening a new one.


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