VersionMark

VersionMark is a tool for capturing and publishing tool version information across CI/CD environments. It helps track which versions of build tools, compilers, and dependencies are used in different jobs and environments.

Features

• Version Capture: Captures tool versions from CI/CD jobs and saves them to JSON files
• Version Publishing: Publishes captured versions to markdown documentation
• Job-ID Tracking: Associates captured versions with specific CI/CD job identifiers
• Version Consolidation: Collapses common versions across jobs while highlighting conflicts
• OS-Specific Overrides: Supports platform-specific version capture commands
• Configurable: Uses .versionmark.yaml config file to define tools and capture methods
• Multi-Platform Support: Runs on Windows and Linux
• Multi-Runtime Support: Targets .NET 8, 9, and 10

Installation

Install the tool globally using the .NET CLI:

dotnet tool install -g DemaConsulting.VersionMark

Quick Start

1. Create Configuration File

Create a .versionmark.yaml file in your repository:

tools:
  dotnet:
    command: dotnet --version
    regex: '(?<version>\d+\.\d+\.\d+)'
  
  node:
    command: node --version
    regex: 'v(?<version>\d+\.\d+\.\d+)'

2. Capture Tool Versions

In your CI/CD job, capture tool versions with a job identifier:

versionmark --capture --job-id "windows-net8"

This creates a JSON file with captured versions (e.g., versionmark-windows-net8.json).

3. Publish to Documentation

After all jobs complete, publish the captured versions to markdown:

versionmark --publish --report versions.md

This consolidates versions from all jobs and generates a markdown report.

Command-Line Options

Global Options

Option	Description
-v, --version	Display version information
-?, -h, --help	Display help message
--silent	Suppress console output
--log <file>	Write output to log file

Capture Mode

Capture tool versions from the current environment:

versionmark --capture --job-id <job-identifier> [options] [-- tool1 tool2 ...]

Option	Description
--capture	Enable capture mode
--job-id <id>	(Required) Unique identifier for this CI/CD job
--output <file>	Output JSON file (default: versionmark-<job-id>.json)
-- <tools...>	List of tool names to capture (default: all tools in config)

Example: Capture specific tools only:

versionmark --capture --job-id "windows-build" -- dotnet node npm

Publish Mode

Publish captured versions to markdown documentation:

versionmark --publish --report <file> [options] [-- pattern1 pattern2 ...]

Option	Description
--publish	Enable publish mode
--report <file>	(Required) Output markdown file path
--report-depth <depth>	Heading depth for markdown output (default: 2)
-- <patterns...>	Glob patterns for JSON files (default: versionmark-*.json)

Configuration File

The .versionmark.yaml file defines which tools to capture and how to extract their versions:

tools:
  # Basic tool definition
  dotnet:
    command: dotnet --version
    regex: '(?<version>\d+\.\d+\.\d+)'
  
  # Tool with OS-specific overrides
  gcc:
    command: gcc --version
    command-win: gcc.exe --version
    command-linux: gcc-13 --version
    command-macos: gcc-14 --version
    regex: 'gcc \(.*\) (?<version>\d+\.\d+\.\d+)'
    regex-win: 'gcc\.exe \(.*\) (?<version>\d+\.\d+\.\d+)'
    regex-linux: 'gcc-13 \(.*\) (?<version>\d+\.\d+\.\d+)'
  
  # Tool with custom output parsing
  cmake:
    command: cmake --version
    regex: 'cmake version (?<version>\d+\.\d+\.\d+)'

Configuration Options

Each tool in the tools dictionary has the following properties:

• command: Shell command to execute to get version information
• regex: Regular expression with a named 'version' capture group using .NET syntax (?<version>...)
• command-win: (Optional) Command override for Windows
• command-linux: (Optional) Command override for Linux
• command-macos: (Optional) Command override for macOS
• regex-win: (Optional) Regex override for Windows
• regex-linux: (Optional) Regex override for Linux
• regex-macos: (Optional) Regex override for macOS

Output Format

Capture Output (JSON)

Capture mode creates a JSON file with the following structure:

{
  "JobId": "windows-net8",
  "Versions": {
    "dotnet": "8.0.100",
    "node": "20.11.0",
    "gcc": "13.2.0"
  }
}

Publish Output (Markdown)

Publish mode generates a markdown list consolidating versions from all jobs:

## Tool Versions

- **dotnet**: 8.0.100
- **gcc**: 11.4.0 (windows-net8)
- **gcc**: 13.2.0 (linux-net8)
- **node**: 20.11.0

When a tool has the same version across all jobs, it's shown without job identifiers. When versions differ, each version is listed on a separate line with the jobs that use it shown in parentheses.

Documentation

Generated documentation includes:

• Build Notes: Release information and changes
• User Guide: Comprehensive usage documentation
• Code Quality Report: CodeQL and SonarCloud analysis results
• Requirements: Functional and non-functional requirements
• Requirements Justifications: Detailed requirement rationale
• Trace Matrix: Requirements to test traceability

License

Copyright (c) DEMA Consulting. Licensed under the MIT License. See LICENSE for details.

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