[FEATURE] Docs: producer guide for ref inheritance (git: parent / relative path) in monorepo bundles so #branch is not required

Open Beginner friendly
  • Is something wrong?
#3,452 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
60/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
python, yaml
Domain
documentation

Research direction

Start by confirming the behaviour in expand_parent_repo_decl in src/apm_cli/deps/apm_resolver.py, then read producer/repo-shapes.md (Monorepo-hybrid) and producer/source-vs-installed.md. Done means a Monorepo-hybrid subsection with the before/after apm.yml examples, a note that top-level #ref does not propagate to transitive git: dependencies, a cross-link from source-vs-installed, and a schema-reference link back. Confirm scope with maintainers first, since the issue awaits approval.

Written by the indexing model from the issue text.

Description

Problem

I maintain a monorepo with a bundle and several plugins/skills (the "monorepo-hybrid" shape from [Repo shapes](https://microsoft.github.io/apm/producer/repo-shapes/)). The bundle's apm.yml referenced its sibling plugins with full git: coordinates:

dependencies:
  apm:
    - git: acme/ai-monorepo
      path: plugins/plugin-a
    - git: acme/ai-monorepo
      path: skills/skill-b

When a change is on a feature branch and I ask a colleague to review it, they run:

apm install acme/ai-monorepo/bundles/my-bundle#feature-x

The bundle itself resolves from feature-x, but every plugin/skill listed in its apm.yml resolves from the repository's default branch, because the #ref given at the top level is not propagated to transitive git: dependencies that carry their own full coordinates.

The only workaround we found was to add ref: feature-x to every entry, then remove those lines again before merging. The manifest that was reviewed is therefore not the one that gets merged, which is poor practice and easy to get wrong.

After reading the resolver source, I found that APM already supports the required behaviour: expand_parent_repo_decl in src/apm_cli/deps/apm_resolver.py inherits the parent's resolved ref when a child uses git: parent, and same-repo relative path: entries are expanded to the parent's host/repo/ref as well.

Rewriting the bundle as:

dependencies:
  apm:
    - git: parent
      path: plugins/plugin-a
    - git: parent
      path: skills/skill-b

means apm install .../my-bundle#feature-x pulls everything from feature-x, and apm install .../my-bundle after the merge pulls everything from main, with no edits to apm.yml in between.

The problem is discoverability. Searching the docs for git: parent finds it in only three places:

  • Manifest schema -- 4.1.2 object form: The only example, with the single sentence "When ref is omitted the parent's resolved ref is inherited."
  • Manage dependencies: One sentence listing the accepted keys.
  • The OpenAPM v0.1 specification.

Nothing under producer/ mentions it. In particular:

  • Repo shapes -- Monorepo-hybrid shows plugins/plugin-a/apm.yml and plugins/plugin-b/apm.yml side by side but never shows how one package in that repo should declare a dependency on a sibling.
  • Source vs installed tells authors to declare git: + ref: v1.4.0 and "update the declared ref:" when the source changes, which for same-repo siblings is exactly the pattern that causes the edit-before-merge churn described above.
  • No page explicitly states that a top-level #ref does not flow down to transitive dependencies that have their own full git: coordinates, so authors assume it does and are surprised when main is installed.
Proposed documentation change

Add a short, task-oriented section to the producer docs (I think producer/repo-shapes.md under Monorepo-hybrid is the natural home, with a cross-link from producer/source-vs-installed.md) covering:

  1. Ref inheritance: The #ref passed to apm install (or ref: on a top-level dependency) applies to that dependency only. Transitive dependencies with full git: coordinates resolve their own ref (default branch when omitted).

  2. Same-repository dependencies: For same-repo siblings, use git: parent + path: (or a relative path: that stays inside the repo) so the child inherits the parent's resolved ref. Include the before/after apm.yml examples above.

  3. Feature-branch workflow: Review a feature branch with apm install owner/repo/bundles/x#branch, merge, then consumers run apm install owner/repo/bundles/x, with no change to apm.yml between the two. Explain that the lockfile records the expanded concrete coordinates, so reproducibility is unaffected.

  4. Limitations and compatibility: This only works within one repository; a dependency in a different repository still needs an explicit ref: to track a non-default branch. Document the versions in which each form became available (git: parent in 0.13.0, remote relative path: in 0.20.0) for users on older releases.

Acceptance criteria: A reader following the monorepo-hybrid walkthrough can find how to make a bundle's sibling dependencies follow the install-time ref without reading the schema reference, and the manifest-schema entry links back to that guidance.

Alternatives considered
  • Propagating the top-level #ref to all transitive dependencies: This would override deliberate pins in third-party packages. git: parent already expresses the intended inheritance behaviour precisely. This is a documentation gap, not a behaviour gap.
  • Relying exclusively on the schema reference: The reference is complete, but it is a normative field table and not where a producer looks when setting up a monorepo or a review workflow.
Additional context
  • git: parent was introduced in 0.13.0 (#1149); remote relative path: expansion in 0.20.0 (#1732).
  • Related resolver issues in the same area that readers may hit: #3071 (transitive git+path monorepo regression), #3392 (stale parent manifest on apm update).
  • Suggested labels: type/docs, area/package-authoring, area/docs-site.
  • I am happy to write the docs PR once scope is approved.
Dominant language
Python
Stars
4.3k
Forks
415
Avg merge
3d 3h
Merged PRs (30d)
120

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/apm

All issues in microsoft/apm

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.