DemaConsulting.BuildMark 0.4.1

BuildMark

Markdown Build Notes Generation Tool

Overview

BuildMark is a .NET command-line tool that generates comprehensive markdown build notes reports from Git repository history and GitHub issues. It analyzes commits, pull requests, and issues to create human-readable build notes, making it easy to integrate release documentation into your CI/CD pipelines and documentation workflows.

For a detailed explanation of how BuildMark works internally, see the Theory of Operations.

Features

• 📄 Git Integration - Analyze Git repository history and tags
• 📝 Markdown Reports - Generate human-readable build notes from repository data
• 🐛 Issue Tracking - Extract bug fixes and changes from GitHub issues and pull requests
• 🎯 Customizable Output - Configure report depth and version ranges
• 🚀 CI/CD Integration - Automate build notes generation in your pipelines
• 🌐 Multi-Platform - Support for Windows, Linux, macOS with .NET 8, 9, and 10
• ✅ Self-Validation - Built-in tests without requiring external tools
• 📊 Detailed Reporting - Track changes, bug fixes, and known issues between versions
• 🔍 Linting Enforcement - markdownlint, cspell, and yamllint enforced on every CI run
• 📋 Continuous Compliance - Compliance evidence generated automatically on every CI run, following the Continuous Compliance methodology
• ☁️ SonarCloud Integration - Quality gate and security analysis on every build
• 🔗 Requirements Traceability - Requirements linked to passing tests with auto-generated trace matrix

Installation

Prerequisites

• .NET SDK 8.0, 9.0, or 10.0

Global Installation

Install BuildMark as a global .NET tool for system-wide use:

dotnet tool install --global DemaConsulting.BuildMark

Verify the installation:

buildmark --version

Local Installation

Install BuildMark as a local tool in your project (recommended for team projects):

dotnet new tool-manifest  # if you don't have a tool manifest already
dotnet tool install DemaConsulting.BuildMark

Run the tool:

dotnet buildmark --version

Update

To update to the latest version:

# Global installation
dotnet tool update --global DemaConsulting.BuildMark

# Local installation
dotnet tool update DemaConsulting.BuildMark

Compatibility

Usage

Basic Usage

Run the tool with the --help option to see available commands and options:

buildmark --help

This will display:

Usage: buildmark [options]

Options:
  -v, --version                Display version information
  -?, -h, --help               Display this help message
  --silent                     Suppress console output
  --validate                   Run self-validation
  --results <file>             Write validation results (TRX or JUnit format)
  --log <file>                 Write output to log file
  --build-version <version>    Specify the build version
  --report <file>              Specify the report file name
  --report-depth <depth>       Specify the report markdown depth (default: 1)
  --include-known-issues       Include known issues in the report

Quick Start Examples

Generate build notes for the current version:

buildmark --build-version v1.2.3 --report build-notes.md

Generate build notes with custom markdown depth:

buildmark --build-version v1.2.3 --report build-notes.md --report-depth 2

Include known issues in the report:

buildmark --build-version v1.2.3 --report build-notes.md --include-known-issues

Run self-validation:

buildmark --validate

Run self-validation with test results output:

buildmark --validate --results validation-results.trx

Self Validation

Running self-validation produces a report containing the following information:

# DEMA Consulting BuildMark Self-validation

| Information         | Value                                              |
| :------------------ | :------------------------------------------------- |
| BuildMark Version   | <version>                                          |
| Machine Name        | <machine-name>                                     |
| OS Version          | <os-version>                                       |
| DotNet Runtime      | <dotnet-runtime-version>                           |
| Time Stamp          | <timestamp> UTC                                    |

✓ BuildMark_MarkdownReportGeneration - Passed
✓ BuildMark_GitIntegration - Passed
✓ BuildMark_IssueTracking - Passed
✓ BuildMark_KnownIssuesReporting - Passed

Total Tests: 4
Passed: 4
Failed: 0

Each test in the report proves:

• BuildMark_MarkdownReportGeneration - Markdown report is correctly generated from mock data.
• BuildMark_GitIntegration - Git repository connector reads version tags and commits.
• BuildMark_IssueTracking - GitHub issue and pull request tracking works correctly.
• BuildMark_KnownIssuesReporting - Known issues are correctly included when requested.

See the User Guide for more details on the self-validation tests.

On validation failure the tool will exit with a non-zero exit code.

Report Format

The generated markdown report includes:

1. Build Report Header - Title with version information
2. Version Information - Current version, baseline version, and commit details
3. Changes - List of non-bug changes implemented in this build
4. Bugs Fixed - List of bugs resolved in this build
5. Known Issues - Optional list of known issues (when --include-known-issues is specified)
6. Complete Changelog - Link to the full changelog on GitHub (when available)

Example report structure:

# Build Report

## Version Information

**Version:** 1.2.3
**Baseline Version:** 1.2.0
**Commit:** abc123def456

## Changes

- [#42](https://github.com/owner/repo/pull/42): Add new feature X
- [#43](https://github.com/owner/repo/pull/43): Improve performance of Y

## Bugs Fixed

- [#40](https://github.com/owner/repo/issues/40): Fix crash when Z is null
- [#41](https://github.com/owner/repo/issues/41): Correct validation logic

## Complete Changelog

[View Full Changelog](https://github.com/owner/repo/compare/v1.2.0...v1.2.3)

Contributing

Contributions are welcome! We appreciate your interest in improving BuildMark.

Please see our Contributing Guide for development setup, coding standards, and submission guidelines. Also review our Code of Conduct for community guidelines.

For bug reports, feature requests, and questions, please use GitHub Issues.

License

This project is licensed under the MIT License - see the LICENSE file for details.

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

Support

• 🐛 Report Bugs: GitHub Issues
• 💡 Request Features: GitHub Issues
• ❓ Ask Questions: GitHub Discussions
• 🤝 Contributing: Contributing Guide

Security

For security concerns and vulnerability reporting, please see our Security Policy.

Acknowledgements

BuildMark is built with the following open-source projects:

• .NET - Cross-platform framework for building applications
• Octokit - GitHub API client library for .NET