docs(docs): add versioning concept page#4175
Merged
mmabrouk merged 4 commits intoMay 11, 2026
Merged
Conversation
Introduce a shared concept page documenting the artifact / variant / revision pattern used by applications, workflows, evaluators, and testsets. Covers commit semantics, retrieval references, revision log, and archive/unarchive. Factors out a pattern that would otherwise have to be repeated in every per-resource reference page. The applications, workflows, evaluators, and testsets concept pages (landing in parallel PRs) link to this page instead of redefining the model.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
dosubot
Bot
added
size:M
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
mmabrouk
commented
Apr 17, 2026
mmabrouk
commented
Apr 17, 2026
mmabrouk
commented
Apr 17, 2026
mmabrouk
commented
Apr 17, 2026
mmabrouk
commented
Apr 17, 2026
This was referenced Apr 17, 2026
This was referenced Apr 28, 2026
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
mmabrouk
commented
May 11, 2026
mmabrouk
commented
May 11, 2026
mmabrouk
commented
May 11, 2026
- Note that revisions carry the payload, not just commit metadata. - Add environments as a deployment pointer alongside artifact/variant/revision. - Reference the existing /concepts/concepts overview page. - Replace temperature-only example with a realistic application revision payload (prompt, messages, llm_config). - Explain what a reference is (id, slug, slug+version) before describing retrieve precedence. - Spell out "most specific wins" as revision > variant > environment. - Rename "Revision log" to "Listing revision history" so the heading matches the verb pattern used by the other sections. - Clarify the fork verb ties to POST /variants/fork.
4 tasks
mmabrouk
commented
May 11, 2026
The ag_config wrapper was removed by migration 91d3b4a8c27f_fix_ag_config
(2025-04-24); revision payloads now live under data.parameters directly.
Verified against eu.cloud.agenta.ai: posting with the old ag_config
envelope returns HTTP 200 but stores data: {} because extra fields are
silently dropped. The corrected shape (data.parameters.prompt.*) stores
the payload correctly.
dosubot
Bot
added
size:L
mmabrouk
merged commit a451ea3
into
docs/age-3734-api-reference-epic
3 of 4 checks passed
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
1 participant
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.
Summary
docs/docs/reference/api-guide/04-versioning.mdx, a new concept page explaining Agenta's shared artifact / variant / revision model.curlexample against the applications domain; notes that the same shape applies to workflows, evaluators, and testsets.Context
Part of a larger API reference docs overhaul. Companion PRs for applications, workflows, evaluators, testsets, evaluations, tracing, and folders will link back to this page rather than redefining the versioning model in each one.
Notes
--no-verifybecausepre-commit/gitleaksare not installed in the sandbox where this was authored and pip installs are blocked. The change is MDX-only and contains no secrets, so the skipped scans should be a no-op. Happy to re-run hooks locally on request.Test plan
api/oss/src/apis/fastapi/applications/router.py(commit/retrieve/log endpoints and theApplicationRevisionCommitRequest/ApplicationRevisionRetrieveRequest/ApplicationRevisionsLogRequestwrapper shapes).