"Expressing" a release for an internal mono-repo marketplace

[rcollette]

Given an mono-repo marketplace, comprised of many packages that have their own release numbers, what would be considered a best practice for expressing a github release within that github repo? Is it even necessary?

I'm looking at it as a sort of quick check that people can do when visiting the repo, but I suppose they can hot link our root CHANGELOG.md and do the same thing. We have package specific README.md files and a bump script that copies changelogs from each package in the MR to the masterchange log and runs apm pack --target all.

[danielmeppiel]

Good question — and the answer is "yes, it's worth doing, and we now have the primitives to make it cheap." Shipping in apm 0.14.0 (#1372) and apm-action v1.9.0 (microsoft/apm-action#44).

Versioning strategy decision matrix — see Versioning strategies for the full table. The short version:

Strategy	When to use	apm.yml
lockstep (default)	All packages share one version	marketplace.versioning.strategy: lockstep
tag_pattern	Per-package versions, single GH Release per repo with all packages bumped at once	strategy: tag_pattern + tag_pattern: "{name}-v{version}" per package
per_package	Per-package versions, separate GH Release per package	strategy: per_package + per-package tag_pattern

For your case (per-package versions, sounds like one GH Release per "bump batch"), tag_pattern is the fit:

marketplace:
  versioning:
    strategy: tag_pattern
  packages:
    - name: pkg-one
      version: 2.3.1
      tag_pattern: "{name}-v{version}"   # pkg-one-v2.3.1
    - name: pkg-two
      version: 1.0.0
      tag_pattern: "{name}-v{version}"   # pkg-two-v1.0.0

Is the GH Release necessary? Functionally no — your bump script + master CHANGELOG.md does the job of "what changed when." But a GH Release earns its keep on three axes:

1. Discoverability. gh release list / the repo's Releases tab is the canonical place users look. A linked tarball with sha256 is easier to point at than a commit range.
2. Per-package CHANGELOG slicing. With mode: release, the action automatically generates release notes that group "what changed in this batch" by package, so the GH Release page becomes a per-batch index into your master CHANGELOG instead of a duplicate of it.
3. Drift gate. apm pack --check-clean (new in 0.14) refuses to publish if your committed marketplace.json doesn't match what apm pack would generate from apm.yml right now — catches the "I forgot to re-pack after bumping" class of bug at release time.

Your bump script + apm pack --target all becomes:

# .github/workflows/release.yml
on:
  push:
    tags: ['release-*']   # or your own pattern
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: microsoft/apm-action@v1
        with:
          mode: release
          release-tag: ${{ github.ref_name }}

The action runs --check-versions (enforces your tag_pattern alignment) + --check-clean (drift) before publishing. Misalignment exits 3; drift exits 4. No bash.

Closing this discussion as resolved.

[danielmeppiel]

Follow-up: lockstep golden-path now docs-attested.

The lockstep section in producer/versioning-strategies.md now carries a worked example (shipped in #1384): DevExpGbb/zava-agent-config ships 7 plugins on lockstep. Its apm.yml omits versioning.strategy: (lockstep is the default), declares one top-level version:, and uses build.tagPattern: "v{version}" so a single repo-wide tag (v6.1.2) cuts all 7 tarballs together — verified green on release run 26081432583.

If you want to see the gate fire (apm pack --check-versions --check-clean), the release.yml workflow exercises it on every tag push via microsoft/apm-action@v1 mode: release.

The tag_pattern and per_package sections of the doc remain example-less for now. When a real producer ships on either strategy, we'll fan out the worked-example pattern. Requires apm 0.14.0 + apm-action v1.9.1 or newer.