Conversation
kushnaidu
requested review from
efiacor,
kispaljr,
liamfallon and
mozesl-nokia
as code owners
October 1, 2026 13:33
✅ Deploy Preview for kptdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
📄 Knowledge review✏️ Suggested updates1 page suggestion needs review.
|
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Generated CLI help remains stale, related get documentation is incomplete, and copy-merge’s root Kptfile exception is undocumented.
Review effort: Balanced
Findings: 1
Open (3)
What changed in this PR
Documents all four package-update strategies and corrects resource-merge conflict behavior.
Changes:
- Adds
copy-mergedocumentation. - Clarifies that resource-merge conflicts favor upstream values.
- Updates related guidance and examples.
| File | Description |
|---|---|
documentation/content/en/reference/cli/pkg/update/_index.md |
Expands strategy reference and conflict semantics. |
documentation/content/en/guides/3-way-merge.md |
Updates strategy guide, examples, and best practices. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
kushnaidu
force-pushed
the
merge-strategy-docs
branch
from
October 1, 2026 13:42
07cd018 to
f7c9390
Compare
Corrects and completes the kpt package update-strategy documentation to match the implementation in pkg/lib/update. - Add the copy-merge strategy, which was missing from both the `kpt pkg update` and `kpt pkg get` --strategy references and from the 3-way-merge guide, even though it is a registered strategy (UpdateStrategiesAsStrings) accepted by both commands. - Fix the 3-way-merge guide's conflict description: resource-merge does not fail on a field changed in both upstream and local. It auto-resolves by taking the upstream value and succeeds, with no conflict markers. - Clarify that copy-merge 3-way merges the root Kptfile (via UpdateKptfile) instead of overwriting it, so "any file" no longer misleads users about local root-Kptfile customizations. - Regenerate internal/docs/generated/pkgdocs/docs.go so the CLI long help for `kpt pkg get` and `kpt pkg update` is no longer stale. Signed-off-by: Kushal Harish Naidu <kushal.harish.naidu@ericsson.com>
kushnaidu
force-pushed
the
merge-strategy-docs
branch
from
October 1, 2026 14:03
f7c9390 to
7eddc34
Compare
Signed-off-by: Kushal Harish Naidu <kushal.harish.naidu@ericsson.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Several statements overgeneralize upstream-wins behavior and local-file preservation beyond the implementation.
Review effort: Balanced
Findings: 6
Open (6)
Resolved since last review (3)
Make the resource-merge conflict description more precise: the upstream value wins only for different non-null scalar / non-associative-list values; local field removals and nulls follow separate deletion semantics (and honor --preserve-explicit-null). Clarify the copy-merge root-Kptfile exception (local-only non-conflicting edits preserved; conflicting values follow the Kptfile merge rules; upstream metadata refreshed) and the local-vs-upstream same-path file behavior. Signed-off-by: Kushal Harish Naidu <kushal.harish.naidu@ericsson.com>
|
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Corrects and completes the kpt package update-strategy documentation so it
matches the actual implementation in
pkg/lib/update.1. Add the missing
copy-mergestrategy.copy-mergeis a registered update strategy (returned byUpdateStrategiesAsStrings()and accepted by bothkpt pkg updateandkpt pkg get), but it was absent from the docs. Added it to:reference/cli/pkg/update/_index.md—--strategyflag list and a new"Copy-merge strategy" details subsection.
reference/cli/pkg/get/_index.md—--strategyflag list.guides/3-way-merge.md— changed "three strategies" to "four" and added acopy-mergesection.2. Fix the conflict behavior for
resource-merge.The 3-way-merge guide previously stated that a conflict causes the update to
fail with an error. The implementation (
merge3/visitor.go,VisitScalar)does the opposite: when a field is changed in both upstream and local, it
auto-resolves by taking the upstream value and the update succeeds, with no
conflict markers. Rewrote the "Handling Conflicts" section and adjusted the
related best-practices and fast-forward wording. Also added a matching note to
the effective-customizations chapter (
book/07).3. Clarify the copy-merge root-Kptfile exception.
copy-merge is a file-level overwrite for most files, but the root Kptfile is an
exception:
CopyMergeUpdater3-way merges it viaUpdateKptfileandCopyPackagethen skips the already-present root Kptfile, so local root-Kptfilecustomizations are preserved. Reworded "any file" so it no longer misleads users
about this case.
4. Regenerate the committed CLI help.
commands/pkg/update/cmdupdate.goandcommands/pkg/getserve their long helpfrom the checked-in generated
internal/docs/generated/pkgdocs/docs.go, whichstill omitted
copy-merge. Regenerated it (make generate) so the CLI--helptext is no longer stale.Motivation
The 3-way-merge guide's conflict section contradicted both the CLI reference and
the actual code, which could lead users to expect an interactive conflict
resolution that never happens — risking silent loss of local edits. The missing
copy-mergestrategy left a valid, user-facing option undocumented.Verified against the update code and by reproducing all four strategies'
behavior (including the field-level conflict and the "deleted upstream but
modified locally" case) with
kpt pkg update.