Contributing

Contribute to the public CLI repository: dziblo-music/agoraform. This page summarizes CONTRIBUTING.md at tag v0.3.0.

Before starting

For significant changes, work from an existing GitHub issue or open one first. Small documentation fixes and obvious bug fixes do not necessarily require a separate issue.

Prerequisites

• Go 1.26.7 or newer
• Git

Fork or clone the repository and create a branch from the latest main:

issue-<number>-<short-description>

Example: issue-12-google-conversion-action.

Build and run

go build -o agoraform ./cmd/agoraform
./agoraform --help
./agoraform --version

On Windows, the binary is typically agoraform.exe.

Test and lint

gofmt -w .
go test ./...
go vet ./...

CI also checks that gofmt would not change any files. Run gofmt -l . locally and ensure it prints nothing before opening a pull request.

Do not commit API tokens, credentials, personal data, or machine-local paths.

Pull requests

Open pull requests against main. Keep each PR focused.

Include the related issue, a summary, tests performed, important design decisions, and documentation changes where applicable.

Use Closes #123 when the PR should close an issue after merge. Use Refs #123 when the issue has post-merge acceptance work, such as release artifact verification.

All required CI checks must pass before merge.

Design principles

Agoraform prioritizes declarative configuration, deterministic plans, safe infrastructure changes, a provider-independent core, provider-native capabilities, reviewable Git-based workflows, and secure credential handling.

agoraform plan must never mutate provider resources. Destructive operations should not be introduced without explicit design and safety consideration.

Provider tests must not depend on production accounts or credentials.

Compatibility

Agoraform follows Semantic Versioning 2.0.0. Git tags are v plus the SemVer identifier. agoraform --version prints the identifier without the prefix.

Until 1.0.0, a MINOR bump in the 0.x series may include breaking CLI or manifest changes. Those changes must still be intentional and documented in CHANGELOG.md.

Contributions are accepted under the Apache License 2.0.

Release packaging is documented in the CLI repository at docs/release.md (v0.3.0).