Skip to content

Latest commit

 

History

History
291 lines (205 loc) · 8.14 KB

CONTRIBUTING.md

File metadata and controls

291 lines (205 loc) · 8.14 KB

Contributing to SarifMark

Thank you for your interest in contributing to SarifMark! We welcome contributions from the community and appreciate your help in making this project better.

Code of Conduct

This project adheres to a Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior through GitHub.

How to Contribute

Reporting Bugs

If you find a bug, please create an issue on GitHub with the following information:

  • Description: Clear description of the bug
  • Steps to Reproduce: Detailed steps to reproduce the issue
  • Expected Behavior: What you expected to happen
  • Actual Behavior: What actually happened
  • Environment: Operating system, .NET version, SarifMark version
  • Logs: Any relevant error messages or logs

Suggesting Features

We welcome feature suggestions! Please create an issue on GitHub with:

  • Feature Description: Clear description of the proposed feature
  • Use Case: Why this feature would be useful
  • Proposed Solution: Your ideas on how to implement it (optional)
  • Alternatives: Any alternative solutions you've considered (optional)

Submitting Pull Requests

We follow a standard GitHub workflow for contributions:

  1. Fork the repository
  2. Clone your fork locally
  3. Create a branch for your changes (git checkout -b feature/my-feature)
  4. Make your changes following our coding standards
  5. Test your changes thoroughly
  6. Commit your changes with clear commit messages
  7. Push to your fork
  8. Create a Pull Request to the main repository

Development Setup

Prerequisites

  • .NET SDK 8.0, 9.0, or 10.0
  • Git
  • A code editor (Visual Studio, VS Code, or Rider recommended)

Getting Started

  1. Clone the repository:

    git clone https://github.com/demaconsulting/SarifMark.git
cd SarifMark

  2. Restore dependencies:

    dotnet tool restore
dotnet restore

  3. Build the project:

    dotnet build --configuration Release

  4. Run tests:

    dotnet test --configuration Release

Coding Standards

General Guidelines

  • Follow the C# Coding Conventions
  • Use clear, descriptive names for variables, methods, and classes
  • Write XML documentation comments for all public, internal, and private members
  • Keep methods focused and single-purpose
  • Write tests for new functionality

Code Style

This project enforces code style through .editorconfig. Key requirements:

  • Indentation: 4 spaces for C#, 2 spaces for YAML/JSON/XML
  • Line Endings: LF (Unix-style)
  • Encoding: UTF-8
  • Namespaces: Use file-scoped namespace declarations
  • Braces: Required for all control statements
  • Naming Conventions:
    • Interfaces: IInterfaceName
    • Classes/Structs/Enums: PascalCase
    • Methods/Properties: PascalCase
    • Parameters/Local Variables: camelCase

XML Documentation

All members require XML documentation with proper indentation:

/// <summary>
///     Brief description of what this does.
/// </summary>
/// <param name="parameter">Description of the parameter.</param>
/// <returns>Description of the return value.</returns>
public int ExampleMethod(string parameter)
{
    // Implementation
}

Note the spaces after /// for proper indentation in summary blocks.

Testing Guidelines

Test Framework

We use MSTest v4 for unit and integration tests.

Test Naming Convention

Use the pattern: ClassName_MethodUnderTest_Scenario_ExpectedBehavior

Examples:

  • Program_Main_NoArguments_ReturnsSuccess
  • Context_Create_WithInvalidFlag_ThrowsArgumentException
  • SarifResults_Read_ValidFile_ReturnsResults

Writing Tests

  • Write tests that are clear and focused
  • Use modern MSTest v4 assertions:
    • Assert.HasCount(expectedCount, collection)
    • Assert.IsEmpty(collection)
    • Assert.DoesNotContain(item, collection)
  • Always clean up resources (use try/finally for console redirection)
  • Link tests to requirements in requirements.yaml when applicable

Running Tests

# Run all tests
dotnet test --configuration Release

# Run specific test
dotnet test --filter "FullyQualifiedName~YourTestName"

# Run with coverage
dotnet test --collect "XPlat Code Coverage"

Documentation

Markdown Guidelines

All markdown files must follow these rules (enforced by markdownlint):

  • Maximum line length: 120 characters
  • Use ATX-style headers (# Header)
  • Lists must be surrounded by blank lines
  • Use reference-style links: [text][ref] with [ref]: url at document end
  • Exception: README.md uses absolute URLs (it's included in the NuGet package)

Spell Checking

All files are spell-checked using cspell. Add project-specific terms to .cspell.json:

{
  "words": [
    "myterm"
  ]
}

Quality Checks

Before submitting a pull request, ensure all quality checks pass:

1. Build and Test

dotnet build --configuration Release
dotnet test --configuration Release

All tests must pass with zero warnings.

2. Linting

# These commands run in CI - verify locally if tools are installed
markdownlint-cli2 "**/*.md"
cspell "**/*.{md,cs}"
yamllint -c .yamllint.yaml .

3. Code Coverage

Maintain or improve code coverage. Use the --collect "XPlat Code Coverage" option when running tests.

Commit Messages

Write clear, concise commit messages:

  • Use present tense ("Add feature" not "Added feature")
  • Use imperative mood ("Move cursor to..." not "Moves cursor to...")
  • Limit first line to 72 characters
  • Reference issues and pull requests when applicable

Examples:

  • Add support for custom report headers
  • Fix crash when SARIF file path is invalid
  • Update documentation for --report-depth option
  • Refactor argument parsing for better testability

Pull Request Process

  1. Update Documentation: Update relevant documentation for your changes
  2. Add Tests: Include tests that cover your changes
  3. Run Quality Checks: Ensure all linters, tests, and builds pass
  4. Submit PR: Create a pull request with a clear description
  5. Code Review: Address feedback from maintainers
  6. Merge: Once approved, a maintainer will merge your PR

Pull Request Template

When creating a pull request, include:

  • Description: What changes does this PR introduce?
  • Motivation: Why are these changes needed?
  • Related Issues: Link to any related issues
  • Testing: How have you tested these changes?
  • Checklist:
    • Tests added/updated
    • Documentation updated
    • All tests pass
    • Code follows style guidelines
    • No new warnings introduced

Requirements Management

SarifMark uses DemaConsulting.ReqStream for requirements traceability:

  • All requirements are defined in requirements.yaml
  • Each requirement should be linked to test cases
  • Run dotnet reqstream to generate requirements documentation
  • Use the --enforce flag to ensure all requirements have test coverage

Release Process

Releases are managed by project maintainers. The process includes:

  1. Version bump in project files
  2. Tag the release in Git
  3. Build and test across all supported platforms
  4. Publish NuGet package
  5. Create GitHub release with artifacts and release notes

Getting Help

License

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

Thank you for contributing to SarifMark!