Go modules

This repository uses a single repository-wide go.work file at the repository root and a set of Go modules under utils/.

Consumer usage

Depend on the specific submodule that provides the package you import.

Examples:

go get github.com/ARM-software/golang-utils/utils/http@latest
go get github.com/ARM-software/golang-utils/utils/filesystem@latest
go get github.com/ARM-software/golang-utils/utils/validation@latest

Compatibility note: The github.com/ARM-software/golang-utils/utils module remains a lightweight umbrella for compatibility and tooling. New consumers should depend on the narrower submodule they actually import. Submodule tags start with the next CDS project release; v1.170.7 and earlier published only the original umbrella module. If using dependabot, the upgrade and change should be transparent.

If your go.mod still requires a pre-split umbrella version such as github.com/ARM-software/golang-utils/utils v1.170.7, first upgrade that requirement to the first split-aware umbrella release, then add the narrower module you actually import, for example github.com/ARM-software/golang-utils/utils/collection. In a local test, mixing v1.170.7 with the split collection module caused Go to fail with: ambiguous import: found package github.com/ARM-software/golang-utils/utils/collection in multiple modules. Remove the umbrella requirement entirely if you no longer import packages from it. See Ambiguous Imports below for the generic cause and fix pattern.

Ambiguous imports

Go reports an ambiguous import error when the build list contains two modules that both appear to provide the same package import path.

In this repository, the most likely cause is a mixed pre-split and post-split dependency set, for example:

In that situation, Go sees github.com/ARM-software/golang-utils/utils/collection inside both modules and fails instead of guessing which one you meant.

Example error:

go: example.com/my-project imports
    github.com/ARM-software/golang-utils/utils/collection: ambiguous import: found package github.com/ARM-software/golang-utils/utils/collection in multiple modules:
    github.com/ARM-software/golang-utils/utils v1.170.7
    github.com/ARM-software/golang-utils/utils/collection v1.171.0

To fix it:

  1. Upgrade github.com/ARM-software/golang-utils/utils to the first split-aware umbrella release, or remove it entirely if you no longer import packages from that umbrella module.
  2. Add or keep only the narrower modules that match the packages you actually import, such as github.com/ARM-software/golang-utils/utils/collection.
  3. Run go mod tidy and confirm the older umbrella version no longer pulls the same package path into the build list.

If you still see the error, inspect go mod graph or go list -m all to find which dependency is still selecting the older umbrella module.

Workspace structure

CI uses the reusable sync-go-workspace action to run go work sync, then the Go multimodules action to discover modules from go.work. It checks that every go.mod is listed.

Internal dependencies

Internal module dependencies must follow this pattern:

  1. Add a normal require on the repository release version, for example github.com/ARM-software/golang-utils/utils/commonerrors v1.170.7 while preparing the first multi-module release.
  2. Add a local replace pointing at the sibling checkout path, for example replace github.com/ARM-software/golang-utils/utils/commonerrors => ../commonerrors.
  3. Keep replace directives suitable for local development with GOWORK=off.

This keeps local development working before publication. CDS 4.8.0+ is responsible for preparing the versioned internal requirements and tagging all workspace modules as part of the single project release. Go consumers ignore dependency modules' local replace directives and resolve versioned requirements from published CDS tags.

Adding a new module

  1. Create the package directory under utils/.
  2. Add a go.mod whose module path matches the import path.
  3. Add the module path to the repository go.work.
  4. Add versioned require plus local replace directives for internal dependencies.
  5. If the module contains go:generate directives, use go tool and declare only the needed tools in that module's tool block.
  6. Update .github/dependabot.yml so the new go.mod directory is covered.
  7. Ensure CI still discovers the module from go.work.

If the module root would otherwise contain no Go source file, add a small doc.go so Go tooling can still address the module cleanly.

When splitting an existing package into a module, follow the backward-compatible module refactoring guide to preserve consumer imports and dependencies.

Running checks across all modules

From the repository root:

go work sync
go work edit -json |
  sed -n 's/^[[:space:]]*"DiskPath": "\([^"]*\)".*$/\1/p' |
  while IFS= read -r module; do
    (cd "$module" && go generate -tags integration ./... && golangci-lint run --build-tags integration ./... && go test -tags integration ./...)
  done

The composite action's verify task runs those checks with gotestsum, then produces per-module JUnit XML and coverage profiles, plus combined reports, under artifacts/. Local commands use Bash on Linux and macOS; on Windows, use WSL with Go and golangci-lint installed. To confirm that one module builds without workspace resolution, run GOWORK=off go test ./... from its directory.

CI behaviour

The CI workflows call the local Go multimodules composite action with uses: $/actions/go-multimodules. It:

  1. Reads the module list from the repository go.work.
  2. Runs go generate per module.
  3. Runs golangci-lint per module.
  4. Runs tests per module with gotestsum and writes per-module and combined JUnit XML reports.
  5. Writes one coverage profile per module and merges them into a combined profile.
  6. Uploads JUnit and coverage artifacts.
  7. Publishes a GitHub Actions summary listing each module's coverage, failed test cases, and links to the JUnit and coverage artifacts.

See the Go multimodules action guide for a full example using the action from another repository, including the difference between $ and a repository-qualified uses: reference.

CDS releases

CDS remains the only project release mechanism.