Contributing

Cannectors welcomes contributions. The codebase is small, the tests are quick, and the bar for code review is "is this consistent with the surrounding code".

Local dev setup

git clone https://github.com/alexandrecano/cannectors.git
cd cannectors
go mod download
make build           # builds bin/cannectors
make test            # full test suite (~30s)
make lint            # golangci-lint

Requirements:

• Go 1.25+ (see go.mod)
• golangci-lint v2.7.1+ for make lint
• Docker for the local test lab (make test-lab-up)
• make for the canonical commands; the Makefile is short and readable if you'd rather invoke go directly

What to run before opening a PR

make test            # everything must pass
make lint            # zero issues
make validate-examples  # the 33 maintained examples still validate

Three quick gates that match what CI runs.

Conventions

Package layout

Module packages live one-per-type under internal/modules/{input,filter,output}/. Don't introduce sub-packages inside a module unless the module is genuinely large.

Tests

• Co-locate test files with source: foo.go + foo_test.go.
• Use t.Helper() in test helpers so failure messages point at the call site.
• Integration tests against external services (HTTP, SQL) use real containers in the test lab or in-memory test servers — not mocks. Mocks drift; real servers don't.
• Prefer table-driven tests for cases that share scaffolding.

Errors

• Use errors.Join for multi-error returns (validation, batch output). The runtime aggregates them for the user.
• Wrap with fmt.Errorf("...: %w", err) to preserve causality.
• Don't return raw third-party errors at module boundaries — they leak implementation details.

Logging

• Use log/slog with the standard fields (pipeline, module, msg). The output goes to stdout as JSON.
• Don't log credentials. Don't log entire records at info level — use debug if you must.

Commit messages

One-line summary, optional body. Reference issues by number. Examples that match the existing log:

• feat(input): add kafkaConsumer input module
• fix(http_call): honor Retry-After header in 429 responses
• docs: clarify state-persistence ordering across cursors
• chore: bump golangci-lint to v2.8.0

Don't rebase or amend after a review starts — push fix-up commits and squash on merge.

PR checklist

Before clicking "Ready for review":

• make test is green.
• make lint reports zero issues.
• Any new module is documented under cannectors-doc/content/docs/modules/... and rendered options match the schema.
• A test was added or updated.
• The PR description names the user-facing change (feature, bug fix, refactor).

Reporting bugs / proposing changes

Open an issue on github.com/alexandrecano/cannectors/issues. For non-trivial proposals (new module, schema change), open the issue first to align on the design before opening the PR.

License

Apache 2.0. Contributions are licensed under the same terms by opening the PR.