Contributing to OpenMCF

OpenMCF is an open-source project and welcomes contributions from the community. This guide covers everything you need to set up a development environment, build the project, run tests, and submit changes.

Prerequisites

Before you begin, install the following tools:

Optional but recommended:

Getting the Source

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/<your-username>/openmcf.git
cd openmcf

Verify the build works:

make build

This runs the full build pipeline: proto generation, Bazel Gazelle, CLI compilation, and validation.

Building

Full Build

make build

Runs the complete build pipeline including proto generation, kind map generation, Bazel Gazelle updates, and CLI compilation.

Proto Generation

make protos

Generates Go stubs from Protocol Buffer definitions using Buf. Run this after modifying any .proto file. This target:

1. Runs buf generate to produce Go, TypeScript, and Java stubs
2. Copies generated Go stubs into the apis/ source tree
3. Runs bazel run //:gazelle to update Bazel BUILD files

CLI Only

make build-cli

Cross-compiles the CLI binary for darwin/linux on amd64/arm64.

Kind Map Generation

make generate-cloud-resource-kind-map

Regenerates the cloud resource kind map. Run this after adding a new deployment component to cloud_resource_kind.proto.

Testing

All Tests

make test

Runs all Go tests with race detection enabled:

go test -race -v -count=1 -p 4 ./...

Component-Scoped Tests

For faster iteration when working on a single component, run tests directly in the component's directory:

# Run proto validation tests for a specific component
go test -v ./apis/org/openmcf/provider/aws/awss3bucket/v1/...

# Build check for a Pulumi module
go build ./apis/org/openmcf/provider/aws/awss3bucket/v1/iac/pulumi/...

# Vet check
go vet ./apis/org/openmcf/provider/aws/awss3bucket/v1/iac/pulumi/...

# Validate a Terraform module
cd apis/org/openmcf/provider/aws/awss3bucket/v1/iac/tf
terraform init && terraform validate

Running localized commands avoids rebuilding the entire project for single-component changes.

Linting

# Go formatting
make fmt

# Go vet
make vet

# Proto linting
make buf-lint

Proto linting includes a custom Buf plugin (buf/lint/optional-linter/) that validates scalar fields with default annotations are marked as optional.

Code Style

Go

• Run make fmt before committing
• Run make vet to catch common issues
• Follow standard Go conventions

Protocol Buffers

• Run buf format and buf lint before committing proto changes
• Do not use Java reserved words (static, class, default, switch, etc.) as enum values or field names — Java stub generation will fail
• Scalar fields with defaults must be marked optional and annotated with (org.openmcf.shared.options.default)

Naming Conventions

• Component folders: <provider><resource> in lowercase (e.g., awss3bucket, gcpgkecluster)
• Component kinds: <Provider><Resource> in PascalCase (e.g., AwsS3Bucket, GcpGkeCluster)
• API versions: <provider>.openmcf.org/v1

Submitting Changes

Branch and Commit

1. Create a feature branch from main:

git checkout -b feature/your-feature-name

1. Make your changes following the coding standards above

2. Run tests before committing:

make test

1. Commit with a clear, descriptive message:

git commit -m "feat(aws): add lifecycle rule support to AwsS3Bucket"

Pull Request

1. Push your branch to your fork:

git push origin feature/your-feature-name

1. Open a Pull Request against the main branch

2. Include in your PR description:

   • What the change does and why
   • How to test it
   • Any breaking changes

3. Address review feedback and iterate

Commit Message Format

Follow Conventional Commits:

<type>(<scope>): <subject>

Scope should reflect the affected area: aws, gcp, kubernetes, cli, docs, build.

Communication

• GitHub Issues — Bug reports, feature requests
• GitHub Discussions — Questions, ideas, design proposals
• Discord — Real-time discussion with the community

When proposing larger changes, open a GitHub Issue first to discuss the approach before investing significant effort.

What's Next

• Adding Components — Step-by-step guide for creating new deployment components
• Deployment Components — Understand the anatomy of a component
• Dual IaC Engines — How Pulumi and OpenTofu modules work together