Contributing

Contributions to version are welcome. This guide covers the project conventions and workflow.

Development Environment

Prerequisites

• JDK: 17.0.17 or later
• Scala: 3.7.4
• Git: For version resolution tests
• NodeJS: For JS Platform tests
• Clang / LLVM: For Native Platform tests

Running Tests

sbt test                    # All tests
sbt version-jvm/test        # All JVM Platform Modules
sbt version-native/test     # All Native Platform Modules
sbt version-js/test         # All JS Platform Modules

Tests run on JVM, Scala.js, and Scala Native platforms.

Code Style

Formatting and Linting

sbt format      # Apply scalafmt + scalafix + license headers
sbt check       # Verify formatting compliance

Architecture

Module Structure

Version Resolution

The resolution engine in version-cli-core follows the Technical Specification. Key components:

• version.cli.core.parsing.KeywordParser — extracts version directives from commit messages
• version.cli.core.TargetVersionCalculator — computes target version from keywords and validates targets
• version.cli.core.Resolver — orchestrates the full resolution workflow

Pull Request Guidelines

1. One concern per PR — focused changes are easier to review
2. Include tests — coverage for new functionality and regressions
3. Follow existing patterns — consistency aids maintenance
4. Update documentation — keep README and docs in sync with changes
5. Run static checks — sbt check must pass

Specification Changes

The Technical Specification is normative. If code contradicts the specification, the specification wins. Changes to version resolution behaviour require:

1. Specification update with rationale
2. Implementation changes
3. Comprehensive test coverage
4. Documentation updates

Licence

By contributing, you agree that your contributions will be licensed under the Apache License, Version 2.0.