Change a Public Go Library Without Breaking Its Users' Code

## Check Supported Go Versions and Branches Before Changing Code Treat correctness, backward compatibility, and applicable external specifications as primary acceptance criteria. Before changing code, identify: - the active development branch and the latest stable maintenance branch; - the minimum Go version supported by consumers; - the newer Go version and toolchain required for repository development; - which packages form the public, compatibility-covered API; - which importable internal or experimental packages are outside semantic-version guarantees but still used in practice. Do not assume that “not semver-covered” means “safe to break.” Flag behavior or API changes that could disrupt real users. Route features to the development branch and fixes to the appropriate stable branch according to repository policy. For public packages, avoid standard-library APIs and language features newer than the declared minimum Go version. Keep the compatibility gate executable in the build so unsupported features fail early rather than reaching consumers. ## Run Checks and Tests with the Project's Own Tools Use the project’s task runner and declared formatter instead of substituting familiar commands. The default verification target should combine compilation, license checks, formatting checks, module checks, linting, and fast tests. Maintain two test tiers: - a short race-enabled suite for rapid feedback; - a full integration suite with the repository’s required service dependencies and extended timeout. If integration tests share server state, run the full suite serially and never increase parallelism merely to reduce runtime. Support configurable service endpoints, while keeping a documented local default. Run cross-architecture lint or compilation checks when low-level behavior depends on architecture. In particular, verify 32-bit targets when atomic access is used: 64-bit atomically accessed fields must have safe alignment, such as placement at the start of a struct or use of typed atomic wrappers. ## Match the Library's Patterns for Errors and Public APIs Match the repository’s established patterns: - wrap errors with context using `%w`, and compare them with `errors.Is` or `errors.As` rather than matching message text; - make `context.Context` the first argument of every blocking public method and derive deadlines from the caller’s context instead of creating competing wall-clock timers; - use ordered document types for commands or data whose key order matters, map-like types only when order is irrelevant, and lower-level byte-backed representations only in justified hot paths; - use full words for exported identifiers, add subject-style doc comments, and follow the project’s builder or setter pattern for new options. Preserve current package placement and migration decisions. Do not resurrect removed import paths or obsolete public abstractions. When command monitoring or diagnostics can observe authentication exchanges, add credential-bearing commands to the redaction policy before exposing events. Feature-specific native dependencies and build tags must remain explicit in setup and test instructions. ## Separate Unit and Integration Tests and Run the Ones a Change Needs Place unit tests next to the implementation and integration tests in the repository’s integration area. Use the project assertion helpers and prefer semantic checks such as `ErrorIs` over substring assertions. For integration behavior, use the standard topology-aware harness for deployment setup, fail-point injection, and event capture. Keep specification fixtures in the designated test-data location, initialize required submodules or fixture sources after cloning, and number prose test cases to match the governing specification when traceability matters. Before review, run the default verification target. Run the full serial suite when the change touches integration behavior or shared server state. A passing narrow unit test is not sufficient evidence for cross-architecture, compatibility, or specification-sensitive changes. ## Prepare a Pull Request with Test Results and Compatibility Impact Use the required work-item prefix in commit messages and pull-request titles. The pull request should explain the user-visible behavior, compatibility impact, test evidence, and branch choice. Add change-specific evidence: - for public API changes, generate the repository’s API report and include it in the pull request; - for breaking user-visible changes, update the relevant migration guide; - for specification work, cite the exact requirement that the implementation satisfies; - for changes to importable experimental packages, call out breakage explicitly even when semantic versioning does not require it. Do not present a change as ready merely because it builds locally. Readiness requires the repository’s default checks plus every directly applicable compatibility, integration, API, and specification gate.