Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
181 lines (125 loc) · 8.45 KB

CONTRIBUTING.md

File metadata and controls

181 lines (125 loc) · 8.45 KB
Raw

Contributing to Architecture as Code

Thank you for your interest in contributing to the Architecture as Code project! This guide will help you understand our development workflow and contribution standards.

Project-wide guidance lives in finos/calm-governance. The Architecture as Code project (also known as CALM) spans several repositories. Its governance policies, contribution guidelines (DCO sign-off, raising issues, pull request etiquette, and the responsible use of AI coding assistants), Code of Conduct and Maintainer roster apply to every repository in the project and are maintained there. This document covers what is specific to this repository: our commit conventions and release process.

Maintainers working in this repository should also read MAINTAINERS_GUIDELINES.md for repository-specific review, triage, merge, release, and onboarding guidance.

🚀 Why We Use Semantic Release

We use Semantic Release to automate our release process for the CLI module, with plans to expand to other modules in the future. This ensures:

  • Consistent versioning following Semantic Versioning principles
  • Automated releases triggered by commit messages
  • Generated changelogs that clearly communicate changes to users
  • Reduced human error in the release process

We enforce conventional commit standards across the entire project to ensure we can easily extend semantic-release to other modules when ready.

📝 Commit Message Format

We follow the Conventional Commits specification. Your commit messages must follow this format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

We accept the following commit types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, etc.)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies
  • ci: Changes to our CI configuration files and scripts
  • chore: Other changes that don't modify src or test files
  • revert: Reverts a previous commit

Scopes

We use scopes to indicate which part of the project is affected:

  • cli: Changes to the CLI package
  • shared: Changes to the shared utilities
  • calm-widgets: Changes to the CALM widgets
  • calm-hub: Changes to the CALM hub
  • calm-hub-ui: Changes to the CALM hub UI
  • docs: Changes to documentation
  • vscode: Changes to VS Code extensions
  • deps: Dependency updates
  • ci: CI/CD related changes
  • release: Release-related changes

Examples

# Feature additions
feat(cli): add new validation command
feat(shared): implement schema parser

# Bug fixes
fix(cli): resolve configuration loading issue
fix(calm-hub): correct API endpoint validation

# Documentation
docs: update installation instructions
docs(cli): add usage examples

# Chores
chore(deps): update dependencies
chore(ci): improve release workflow

💡 Pro Tip

For complete details on our commit message rules, see our commitlint.config.js file which contains all validation rules and accepted scopes.

🎯 Benefits of This Approach

Automated Release Management

  • Version Bumping: Semantic Release automatically determines the next version number for the CLI module based on your commit types:
    • fix: → Patch version (1.0.0 → 1.0.1)
    • feat: → Minor version (1.0.0 → 1.1.0)
    • BREAKING CHANGE: → Major version (1.0.0 → 2.0.0)

Changelog Generation

  • Automatic CHANGELOG.md updates for the CLI module with categorized changes
  • Clear release notes for each version
  • Links to commits and PRs for full traceability

Release Automation (CLI Module)

  • Git tags created automatically for CLI releases
  • GitHub releases with detailed notes
  • NPM packages published automatically
  • No manual version management required for CLI releases

📋 Before You Commit

  • Ensure your commit message follows the conventional format - if you've run npm install at the root of the project - husky will assist with ensuring you don't commit with anything incorrect.
  • Run tests to make sure nothing is broken
  • Update documentation if you're adding new features
  • Consider the appropriate scope for your changes

Import Formatting

Use spaces inside named-import braces. ESLint enforces this consistently across the TypeScript workspaces:

import { CalmWidget } from './types';

🛠️ Building and Testing

Building from source

Use Node 26 (nvm use reads .nvmrc) and run everything from the repository root:

npm ci                      # install every workspace from the single root lockfile
npm run build               # build all TypeScript workspaces in dependency order
./mvnw clean install        # build the Java modules (CALM Hub, calm-models)

npm run build:cli builds the CLI and only the packages it depends on. Package-specific build notes are in each package's AGENTS.md. There are no private or undocumented release steps: the release workflows in .github/workflows run exactly these commands.

When and how tests run

  • Locally: run npm test from the repository root to test every TypeScript workspace, or npm test --workspace <name> for one package. Java modules are tested with ./mvnw verify from the root (or cd calm-hub && ../mvnw verify for CALM Hub, which also enforces its coverage gate). Lint with npm run lint.
  • On every pull request: the build-* workflows in .github/workflows build, lint and test each affected package (they are path-filtered, so only the packages touched by the change run), and CLI ↔ CalmHub smoke exercises the CLI against a live Hub. CodeQL, Semgrep and Dependency Review also run on every pull request; see SECURITY.md for the policy behind them.
  • On main and at release: the same workflows run on push. The release workflows build the package they publish and refuse to publish unless the build and test workflows for that package have passed on main. The CLI and CALM Server release workflows also require a passing OSV Scanner run for the commit they release.

Test policy

Every change that adds or modifies functionality must add or update automated tests for that functionality in the affected package's test suite (Vitest for TypeScript, JUnit for Java). Bug fixes must include a regression test that fails without the fix. Reviewers ask for tests before approving; the review checklist is in MAINTAINERS_GUIDELINES.md. Aim for at least 80% coverage on new code.

Responsible Use of AI Coding Assistants

AI coding assistants are welcome, but their output must be treated as draft input. Before submitting a PR, contributors must understand and be able to explain all changes, validate behaviour with the project's required checks, and review the full diff for correctness, security, privacy, licensing, and dependency impact.

Do not share credentials, confidential information, or private data with AI services unless authorized. Contributors remain responsible for the entire submission, including any AI-assisted portions.

The full policy is project-wide and is maintained in calm-governance/CONTRIBUTING.md.

🚫 What Not to Do

  • Don't manually update version numbers in package.json
  • Don't manually edit CHANGELOG.md files
  • Don't use non-standard commit message formats

🤝 Need Help?

If you're unsure about commit message formatting or have questions about contributing:

  • Check our commitlint.config.js for detailed rules
  • Look at recent commits for examples
  • Open an issue for clarification

Thank you for helping make Architecture as Code better! 🎉