docs: Add comprehensive documentation for kpt v1.0.0 API stabilization#4466
Open
NETIZEN-11 wants to merge 1 commit intokptdev:mainfrom
Open
docs: Add comprehensive documentation for kpt v1.0.0 API stabilization#4466NETIZEN-11 wants to merge 1 commit intokptdev:mainfrom
NETIZEN-11 wants to merge 1 commit intokptdev:mainfrom
Conversation
NETIZEN-11
requested review from
efiacor,
kispaljr,
liamfallon and
mozesl-nokia
as code owners
✅ Deploy Preview for kptdocs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
dosubot
bot
added
size:XXL
Contributor
There was a problem hiding this comment.
Copilot reviewed 23 out of 24 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,179 @@ | |||
| # kpt Versioning and API Stability | |||
There was a problem hiding this comment.
The documentation file starts with a UTF-8 BOM (Byte Order Mark) character (U+FEFF). While this is technically valid UTF-8, it can cause issues with some tooling and is not recommended. The BOM should be removed from this file and all other newly created documentation files (MIGRATION_V1.md, BACKWARD_COMPATIBILITY.md, SDK_VERSIONING.md, UPSTREAM_MIGRATION.md, ARCHITECTURE_TESTING.md, V1_RELEASE_CHECKLIST.md).
Suggested change
| # kpt Versioning and API Stability | |
| # kpt Versioning and API Stability |
Comment on lines
282
to
347
| // buildRenderStatus constructs a RenderStatus from the tracked pipeline step results. | ||
| func buildRenderStatus(hctx *hydrationContext, hydErr error) *kptfilev1.RenderStatus { | ||
| if len(hctx.mutationSteps) == 0 && len(hctx.validationSteps) == 0 { | ||
| return nil | ||
| } | ||
| rs := &kptfilev1.RenderStatus{ | ||
| MutationSteps: hctx.mutationSteps, | ||
| ValidationSteps: hctx.validationSteps, | ||
| } | ||
| if hydErr != nil { | ||
| var errLines []string | ||
| for _, s := range hctx.mutationSteps { | ||
| if s.ExecutionError != "" { | ||
| errLines = append(errLines, fmt.Sprintf("%s: %s", stepName(s), s.ExecutionError)) | ||
| } else if s.ExitCode != 0 { | ||
| errLines = append(errLines, fmt.Sprintf("%s: exit code %d", stepName(s), s.ExitCode)) | ||
| } | ||
| } | ||
| for _, s := range hctx.validationSteps { | ||
| if s.ExecutionError != "" { | ||
| errLines = append(errLines, fmt.Sprintf("%s: %s", stepName(s), s.ExecutionError)) | ||
| } else if s.ExitCode != 0 { | ||
| errLines = append(errLines, fmt.Sprintf("%s: exit code %d", stepName(s), s.ExitCode)) | ||
| } | ||
| } | ||
| rs.ErrorSummary = strings.Join(errLines, "\n") | ||
| } | ||
| return rs | ||
| } | ||
|
|
||
| func stepName(s kptfilev1.PipelineStepResult) string { | ||
| if s.Name != "" { | ||
| return s.Name | ||
| } | ||
| if s.Image != "" { | ||
| return s.Image | ||
| } | ||
| return s.ExecPath | ||
| } | ||
|
|
||
| // setRenderStatus reads the Kptfile at pkgPath, sets the Rendered condition and RenderStatus, and writes it back. | ||
| func setRenderStatus(fs filesys.FileSystem, pkgPath string, condition kptfilev1.Condition, renderStatus *kptfilev1.RenderStatus) { | ||
| fsOrDisk := filesys.FileSystemOrOnDisk{FileSystem: fs} | ||
| kf, err := kptfileutil.ReadKptfile(fsOrDisk, pkgPath) | ||
| if err != nil { | ||
| klog.V(3).Infof("failed to read Kptfile for render status update at %s: %v", pkgPath, err) | ||
| return | ||
| } | ||
| if kf.Status == nil { | ||
| kf.Status = &kptfilev1.Status{} | ||
| } | ||
| // Replace any existing Rendered condition | ||
| kf.Status.Conditions = slices.DeleteFunc(kf.Status.Conditions, func(c kptfilev1.Condition) bool { | ||
| return c.Type == kptfilev1.ConditionTypeRendered | ||
| }) | ||
| kf.Status.Conditions = append(kf.Status.Conditions, condition) | ||
| kf.Status.RenderStatus = renderStatus | ||
|
|
||
| // Update render status if provided | ||
| if renderStatus != nil { | ||
| kf.Status.RenderStatus = renderStatus | ||
| } | ||
|
|
||
| if err := kptfileutil.WriteKptfileToFS(fs, pkgPath, kf); err != nil { | ||
| klog.V(3).Infof("failed to write render status to Kptfile at %s: %v", pkgPath, err) | ||
| } | ||
| } |
There was a problem hiding this comment.
There are two unused functions that should be removed: (1) setRenderStatus (lines 322-347) is identical to setRenderConditionWithStatus (lines 255-280) defined above it, and only setRenderConditionWithStatus is called in the production code. (2) buildRenderStatus (lines 282-310) is only referenced in tests, not in production code. These should either be removed or if they're intentionally preserved for backward compatibility or future use, they should be clearly documented as such.
This PR adds comprehensive documentation for kpt v1.0.0 API stabilization as part of issue kptdev#4450 (Part 1 of 4). New Documentation Files: - docs/VERSIONING.md: Semantic versioning policy - docs/MIGRATION_V1.md: Migration guide to v1.0.0 - docs/BACKWARD_COMPATIBILITY.md: Compatibility guarantees - docs/SDK_VERSIONING.md: SDK and function catalog versioning - docs/ARCHITECTURE_TESTING.md: Multi-architecture testing - docs/UPSTREAM_MIGRATION.md: Upstream dependency migration - docs/V1_RELEASE_CHECKLIST.md: Release checklist Updated Files: - README.md: Added v1.0.0 announcement and documentation links All documentation is clear, beginner-friendly, and follows consistent formatting without icons or emojis. Part of kptdev#4450
NETIZEN-11
force-pushed
the
feat/issue-4450-pr1-documentation
branch
from
1324825 to
573ae3e
Compare
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
This PR adds comprehensive documentation to support the kpt v1.0.0 API stabilization effort. It provides clear guidance on versioning, migration, backward compatibility, and release processes.
Part of #4450 - Stabilize kpt API to version 1
Changes Made
New Documentation Files
docs/VERSIONING.mddocs/MIGRATION_V1.mddocs/BACKWARD_COMPATIBILITY.mddocs/SDK_VERSIONING.mddocs/ARCHITECTURE_TESTING.mddocs/UPSTREAM_MIGRATION.mddocs/V1_RELEASE_CHECKLIST.mdDocumentation Standards
Target Audience
Related Issues
Checklist