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/utilsmodule 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.7and earlier published only the original umbrella module. If using dependabot, the upgrade and change should be transparent.If your
go.modstill requires a pre-split umbrella version such asgithub.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 examplegithub.com/ARM-software/golang-utils/utils/collection. In a local test, mixingv1.170.7with the splitcollectionmodule 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:
- the umbrella module at a pre-split version such as
github.com/ARM-software/golang-utils/utils v1.170.7 - a newer split module such as
github.com/ARM-software/golang-utils/utils/collection
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:
- Upgrade
github.com/ARM-software/golang-utils/utilsto the first split-aware umbrella release, or remove it entirely if you no longer import packages from that umbrella module. - Add or keep only the narrower modules that match the packages you actually
import, such as
github.com/ARM-software/golang-utils/utils/collection. - Run
go mod tidyand 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
go.worklives at the repository root.utils/is the umbrella module.- Each top-level consumable package under
utils/has its owngo.mod. - Shared helper packages that are reused across module boundaries also have their own
go.modwhen keeping them separate prevents test-only dependencies from leaking into production modules.
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:
- Add a normal
requireon the repository release version, for examplegithub.com/ARM-software/golang-utils/utils/commonerrors v1.170.7while preparing the first multi-module release. - Add a local
replacepointing at the sibling checkout path, for examplereplace github.com/ARM-software/golang-utils/utils/commonerrors => ../commonerrors. - Keep
replacedirectives suitable for local development withGOWORK=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
- Create the package directory under
utils/. - Add a
go.modwhose module path matches the import path. - Add the module path to the repository
go.work. - Add versioned
requireplus localreplacedirectives for internal dependencies. - If the module contains
go:generatedirectives, usego tooland declare only the needed tools in that module'stoolblock. - Update
.github/dependabot.ymlso the newgo.moddirectory is covered. - 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:
- Reads the module list from the repository
go.work. - Runs
go generateper module. - Runs
golangci-lintper module. - Runs tests per module with
gotestsumand writes per-module and combined JUnit XML reports. - Writes one coverage profile per module and merges them into a combined profile.
- Uploads JUnit and coverage artifacts.
- 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.
- All modules share the same repository release version.
- Submodules are not versioned or released independently.
cd-tag-and-releaseremains the release entry point.- In CDS 4.8.0+,
cd-tag-and-releaseupdates versioned internalrequiredirectives and includes them in the shared release commit before tagging and publication. The repository'srelease.ymlrequires this version.