From 74051c549f8b14c0befb5e97ec2eb93f4a6ba019 Mon Sep 17 00:00:00 2001 From: Mara Nikola Kiefer Date: Thu, 30 Apr 2026 15:36:39 +0200 Subject: [PATCH] docs: update refs and clarify versioning details Co-authored-by: Copilot --- docs/src/content/docs/organization-practices/index.mdx | 2 +- .../docs/organization-practices/sharing-workflows.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/organization-practices/index.mdx b/docs/src/content/docs/organization-practices/index.mdx index 12167a54696..a70553aa7d2 100644 --- a/docs/src/content/docs/organization-practices/index.mdx +++ b/docs/src/content/docs/organization-practices/index.mdx @@ -16,4 +16,4 @@ Organization Practices collects guidance that matters at team and enterprise sca ### Sharing Workflows -[Sharing Workflows](/gh-aw/organization-practices/sharing-workflows/) describes how workflows can be reused across repositories and organizations. It covers imports, reusable components, central workflow repositories, and when to use templates or starter repositories. +[Sharing Workflows](/gh-aw/organization-practices/sharing-workflows/) describes how workflows can be reused across repositories and organizations. It covers imports, reusable components, and central workflow repositories. \ No newline at end of file diff --git a/docs/src/content/docs/organization-practices/sharing-workflows.md b/docs/src/content/docs/organization-practices/sharing-workflows.md index f8d3cb6f88a..4c58905f67e 100644 --- a/docs/src/content/docs/organization-practices/sharing-workflows.md +++ b/docs/src/content/docs/organization-practices/sharing-workflows.md @@ -52,13 +52,14 @@ imports: This lets a single shared component serve multiple consuming workflows with different configurations without requiring separate copies. -See [Imports Reference](/gh-aw/reference/imports/#parameterized-imports-useswith) for schema declaration and validation details. +See [Imports Reference](/gh-aw/reference/imports/#calling-a-parameterized-shared-workflow) for schema declaration and validation details. ### 4. Versioning and update flow Enterprise workflow sharing needs a clear versioning model: -- **Semantic versions** (`@v1.2.0`) pin to a stable release and update to the latest compatible patch or minor within the same major via `gh aw update`. +- **Exact release tags** (`@v1.2.0`) pin to a specific immutable release. They do not move on their own, so `gh aw update` will keep fetching that same tagged version unless you change the `source:` ref explicitly. +- **Moving release refs** (`@v1`) follow the latest compatible release within that stream. These are the typical refs to use when you want `gh aw update` to pick up newer upstream releases automatically. - **Branch refs** (`@develop`) track the latest commit on a branch — useful for development integration. - **SHA pins** (`@abc123def`) provide strict reproducibility and never move without an explicit change. @@ -69,7 +70,7 @@ gh aw update ci-doctor # update one workflow gh aw update # update all tracked workflows ``` -Updates use a 3-way merge by default to preserve local edits. Use `--no-merge` to replace the local copy with the upstream version without merging. Semantic version updates stay within the same major version unless `--major` is passed. +Updates use a 3-way merge by default to preserve local edits. Use `--no-merge` to replace the local copy with the upstream version without merging. When the recorded `source:` uses a moving major ref such as `@v1`, `gh aw update` stays within that major line unless `--major` is passed. ### 5. Private and internal sharing controls