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

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#3,452 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
60/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
python, yaml
Lĩnh vực
documentation

Hướng nghiên cứu

Bắt đầu bằng việc xác nhận hành vi của expand_parent_repo_decl trong src/apm_cli/deps/apm_resolver.py, sau đó đọc producer/repo-shapes.md (Monorepo-hybrid) và producer/source-vs-installed.md. Hoàn thành khi có một mục con Monorepo-hybrid với các ví dụ apm.yml trước và sau khi thay đổi, một ghi chú rằng #ref ở cấp cao nhất không lan truyền đến các phụ thuộc git: bắc cầu, một liên kết chéo từ source-vs-installed và một liên kết quay lại tài liệu tham chiếu schema. Hãy xác nhận phạm vi với maintainer trước, vì issue đang chờ phê duyệt.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
Python
Star
4.3k
Fork
415
Merge trung bình
3 ngày 3 giờ
Pull request đã merge (30 ngày)
120

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của microsoft/apm

Tất cả issue của microsoft/apm

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.