CONTRIBUTING.md

Contributing to BuildMark

Thank you for your interest in contributing to BuildMark! 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, BuildMark 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/BuildMark.git
   cd BuildMark

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
• BuildInformation_ToMarkdown_ValidData_ReturnsMarkdown

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)

Mocking and Testing Patterns

When testing classes that depend on external services (like GitHub GraphQL API):

1. Use virtual methods for dependency creation: Classes expose internal virtual methods (e.g., CreateGraphQLClient) that can be overridden in derived test classes
2. Mock HTTP responses: Use MockGitHubGraphQLHttpMessageHandler to simulate GitHub API responses
3. Helper methods: Use built-in helper methods for common responses

Example:

// Create a mock HTTP handler using helper methods
using var mockHandler = new MockGitHubGraphQLHttpMessageHandler()
    .AddCommitsResponse("commit123")
    .AddReleasesResponse("v1.0.0")
    .AddEmptyPullRequestsResponse();

// Create HttpClient and inject into GitHubGraphQLClient
using var mockHttpClient = new HttpClient(mockHandler);
using var client = new GitHubGraphQLClient(mockHttpClient);

// Now the client will use mock responses instead of real API calls
var commits = await client.GetCommitsAsync("owner", "repo", "branch");

See GitHubRepoConnectorTestabilityTests.cs for complete examples.

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"

Self-Validation Tests

# Run self-validation tests
dotnet run --project src/DemaConsulting.BuildMark \
  --configuration Release --framework net10.0 --no-build -- --validate

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)
• Exception: .github/agents/*.md files use inline links so URLs are visible in agent context

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

Run markdown linting:

npx markdownlint-cli2 "**/*.md" "#node_modules"

Run YAML linting:

yamllint .

Run spell checking:

npx cspell "**/*.{md,cs,yaml,json}" --no-progress

3. Code Coverage

Maintain code coverage above 80%:

dotnet test --collect "XPlat Code Coverage"

Requirements Management

BuildMark uses DemaConsulting.ReqStream for requirements traceability:

• All requirements are defined in requirements.yaml
• Each requirement must be linked to at least one test case
• Run dotnet reqstream to generate the requirements documentation
• Use the --enforce flag in CI to ensure all requirements are covered

When adding new features:

1. Add the requirement to requirements.yaml
2. Write tests that validate the requirement
3. Link the tests to the requirement in requirements.yaml

Release Process

Releases follow this process:

1. Create a release issue to track the release
2. Update version references as needed
3. Create a pull request with the release changes
4. Merge the pull request after review
5. Create a GitHub release with the new version tag — CI/CD will automatically build and publish the NuGet package

Pull Request Process

1. Update Documentation: Ensure all documentation is updated to reflect your changes
2. Add Tests: Include tests for new functionality
3. Update Changelog: Add a brief description of your changes
4. Link Issues: Reference any related issues in your PR description
5. Request Review: Request review from maintainers
6. Address Feedback: Respond to review comments promptly

Getting Help

If you need help or have questions:

• GitHub Issues: For bug reports and feature requests — open an issue
• GitHub Discussions: For general questions and discussions — start a discussion
• Pull Request Comments: For questions about specific code changes
• Security Vulnerabilities: Please review the Security Policy before reporting

Thank you for contributing to BuildMark!