Problem

Extension developers currently must reference azd Go packages using pseudo versions (e.g., v0.0.0-20250430002405-5fba40c50969) instead of stable, semantically versioned releases. This creates instability, poor developer experience, and makes it difficult to manage dependencies and compatibility.

Root Cause

The azd Go packages were not initially designed to be leveraged by other projects or tools. Our versioning strategy only targeted the built CLI tool itself (the azd binary), not the underlying Go packages that extension developers need to import.

Current State

• Extension developers import azd packages (like azdext) as dependencies
• These packages use pseudo versions based on git commit hashes (e.g., v0.0.0-20250430002405-5fba40c50969)
• No semantic versioning strategy for packages consumed externally
• No clear separation between public APIs (meant for external use) and internal implementation details
• No documented compatibility guarantees or versioning policies

Impact on Extension Developers

1. Unstable Dependencies: Pseudo versions tied to specific commits make it unclear what changes are included
2. No Compatibility Guarantees: No way to know if upgrading will introduce breaking changes
3. Poor Developer Experience: Difficult to understand which version to depend on
4. Breaking Changes: No clear signal when APIs change in backward-incompatible ways
5. Version Management: Cannot use standard Go module version constraints (e.g., ^1.2.3)

Proposed Solution Direction

Implement a production-grade semantic versioning strategy for externally consumed Go packages, separate from the CLI tool versioning.

Repository Organization

The repository structure needs reorganization to clearly separate concerns:

1. Core CLI Tool (azd)

   • The azd command-line binary
   • Has its own release versioning (e.g., v1.5.0)
   • Internal implementation

2. First-Party Extensions

   • Extensions that reside in the azure-dev repository
   • Maintained by the core team
   • Examples: azure.ai.agents, azure.coding-agent, microsoft.azd.extensions

3. Externally Consumed Packages (Public APIs)

   • Go packages designed for external consumption by extension developers
   • Examples: azdext package and other public APIs
   • Must have semantic versioning (e.g., v1.0.0, v1.1.0, v2.0.0)
   • Clear API stability and compatibility guarantees
   • Documented versioning policy

4. Internal Packages

   • Packages used exclusively by core CLI and internal implementations
   • Not intended for external consumption
   • Can evolve freely without external compatibility concerns
   • Should be clearly marked as internal (e.g., in internal/ directory)

Acceptance Criteria

Versioning Strategy

• Semantic versioning (semver) implemented for all externally consumed packages
• Version numbering independent from CLI tool version
• Clear versioning policy documented (when major/minor/patch versions increment)
• Automated or standardized process for version bumps

Repository Structure

• Clear separation between public APIs and internal packages
• Public packages clearly identified and documented
• Internal packages isolated (e.g., in internal/ directory)
• First-party extensions organized separately from core CLI

API Stability

• Documented compatibility guarantees for public packages
• Deprecation policy and process
• Migration guides when breaking changes occur
• API stability level indicators (alpha, beta, stable)

Developer Experience

• Extension developers can use standard semver constraints (e.g., ^1.2.0)
• Clear documentation on which packages to import
• Examples showing proper dependency management
• Migration path for existing extensions using pseudo versions

Process & Tooling

• CI/CD validation of semver adherence
• Automated detection of breaking changes
• Release notes generation for package versions
• Go module proxy compatibility

Benefits

• Stability: Extension developers can depend on stable, predictable package versions
• Clarity: Clear separation between public and internal APIs
• Compatibility: Semantic versioning provides clear compatibility guarantees
• Developer Experience: Standard Go module version management works as expected
• Evolution: Internal packages can evolve freely without breaking extensions
• Trust: Professional versioning builds confidence in the extension ecosystem

Related Issues

• Extension developer documentation needs
• API stability and compatibility concerns
• Extension framework maturity and production-readiness

Next Steps

1. Design detailed versioning strategy and repository organization
2. Identify all packages that should be public vs. internal
3. Define semver policy (what constitutes major/minor/patch bumps)
4. Create migration plan for existing extensions
5. Implement repository restructuring
6. Update tooling and CI/CD for version management
7. Document public API versioning guarantees