diff --git a/.github/agents/applogger-delivery-engineer.agent.md b/.github/agents/applogger-delivery-engineer.agent.md index 3327c0e..cc76c22 100644 --- a/.github/agents/applogger-delivery-engineer.agent.md +++ b/.github/agents/applogger-delivery-engineer.agent.md @@ -28,6 +28,9 @@ Load the relevant workflow skills under `.github/skills/` based on the task: 5. Do not skip local validation before push. 6. Do not merge Dependabot blindly; review diff, risk, checks, and workflow implications first. 7. Do not finish a feature, fix, or refactor without checking whether docs or changelog need updates. +8. Do not create a tag automatically after every merge to `main`. +9. Documentation-only work may go `dev -> main` without any tag. +10. Tag only when the merged change is release-worthy or the user explicitly wants a versioned release. ## Parallelization Strategy @@ -49,9 +52,18 @@ Use parallel subagents only for exploration and audit. Do not parallelize writes 6. Push `dev` only after local validation passes. 7. Open and verify PR from `dev` to `main`. 8. Merge only after checks pass. -9. After `main` is verified, create and push the release tag. -10. Review open Dependabot PRs and merge only when technically sound. -11. Confirm docs and release state are current. +9. Decide whether the merged change is tag-eligible. +10. Only after `main` is verified and the change is tag-eligible, create and push the release tag. +11. Review open Dependabot PRs and merge only when technically sound. +12. Confirm docs and release state are current. + +## Intent Interpretation + +Interpret user requests strictly: + +1. `merge dev to main` means complete integration to `main`, not release tagging. +2. `create tag`, `publish release`, or `ship version` means evaluate release-tag eligibility first. +3. If the change is docs-only, workflow-only, or internal maintenance, merge may be correct while tagging is not. ## Output Format diff --git a/.github/skills/applogger-change-delivery/SKILL.md b/.github/skills/applogger-change-delivery/SKILL.md index 6b57055..9fcf14f 100644 --- a/.github/skills/applogger-change-delivery/SKILL.md +++ b/.github/skills/applogger-change-delivery/SKILL.md @@ -25,6 +25,8 @@ Trigger phrases include: 3. Before pushing, run local validation relevant to the changed area. 4. If CI behavior changed, validate with local `act` when practical. 5. Review docs impact before push. +6. Do not assume every merged PR should become a release tag. +7. Treat merge-to-main and tag creation as separate decisions. ## Procedure @@ -36,6 +38,7 @@ Trigger phrases include: 6. Push the integrated change to `dev`. 7. Open PR from `dev` to `main`. 8. Merge only after checks are green. +9. Decide whether the merged change is release-tag eligible before invoking the release flow. ## Parallelization Guidance @@ -50,4 +53,4 @@ For larger changes, run read-only subagent passes in parallel before editing or 1. Report local validation results. 2. Report whether docs changed or were intentionally unchanged. 3. Report push/PR status. -4. State whether the change is ready for tag flow or not. \ No newline at end of file +4. State whether the change is tag-eligible, not tag-eligible, or needs explicit release intent. \ No newline at end of file diff --git a/.github/skills/applogger-release-tagging/SKILL.md b/.github/skills/applogger-release-tagging/SKILL.md index c88481e..2cfd6a9 100644 --- a/.github/skills/applogger-release-tagging/SKILL.md +++ b/.github/skills/applogger-release-tagging/SKILL.md @@ -9,7 +9,7 @@ user-invocable: true ## When to Use -Use this skill only after `dev -> main` is merged and `main` is verified. +Use this skill only after `dev -> main` is merged and `main` is verified, and only when the delivered change deserves a release version. Trigger phrases include: @@ -24,10 +24,38 @@ Trigger phrases include: 2. Never tag before `main` is current and verified. 3. Confirm the version source matches the intended tag. 4. Verify the release workflow result after pushing the tag. +5. Do not create a tag for documentation-only changes. +6. Do not create a tag for repo-only workflow, automation, or housekeeping changes unless they intentionally change release behavior or published artifacts. +7. Create a tag only for changes that alter shipped SDK artifacts, runtime behavior, public API, integration behavior, or an intentional release milestone. + +## Tag Eligibility + +Create a tag when at least one of these is true: + +1. `sdk/` code changed in a way that affects published artifacts. +2. Public API behavior changed. +3. Runtime behavior, delivery behavior, or integration behavior changed. +4. The release is intentionally versioned as a milestone even if changes are small. + +Do not create a tag when all of these are true: + +1. Changes are documentation-only. +2. Changes are internal workflow-only. +3. No published artifact behavior changed. +4. No intentional release milestone was requested. + +## User Intent Interpretation + +Interpret requests this way: + +1. `merge dev to main` means integrate reviewed work into `main`; it does not imply tagging. +2. `publish release` or `create tag` means run tag eligibility checks first. +3. For docs-only work, merging to `main` can be correct without creating any tag. ## Procedure 1. Read [release sequence](./references/release-sequence.md). +2. Read [tag decision matrix](./references/tag-decision-matrix.md). 2. Run [release verification](./references/release-verification.md). 3. If release config changed, verify package permissions and version propagation. 4. Confirm the GitHub Release and package publication completed. diff --git a/.github/skills/applogger-release-tagging/references/release-sequence.md b/.github/skills/applogger-release-tagging/references/release-sequence.md index 5233e27..8aab993 100644 --- a/.github/skills/applogger-release-tagging/references/release-sequence.md +++ b/.github/skills/applogger-release-tagging/references/release-sequence.md @@ -7,12 +7,21 @@ Correct order: 3. Open PR `dev -> main`. 4. Merge after green checks. 5. Update local `main`. -6. Create annotated tag from `main`. -7. Push tag. +6. Decide whether the merged change is tag-eligible. +7. Create annotated tag from `main` only if tag-eligible. +8. Push tag. Typical commands: 1. `git checkout main` 2. `git pull origin main` 3. `git tag -a vX.Y.Z -m "Release X.Y.Z"` -4. `git push origin vX.Y.Z` \ No newline at end of file +4. `git push origin vX.Y.Z` + +Docs-only example: + +1. complete docs change +2. push to `dev` +3. open PR `dev -> main` +4. merge after green checks +5. stop there, no tag diff --git a/.github/skills/applogger-release-tagging/references/tag-decision-matrix.md b/.github/skills/applogger-release-tagging/references/tag-decision-matrix.md new file mode 100644 index 0000000..1f6e382 --- /dev/null +++ b/.github/skills/applogger-release-tagging/references/tag-decision-matrix.md @@ -0,0 +1,27 @@ +# Tag Decision Matrix + +Tag is usually required when: + +1. `sdk/` implementation changed and published artifacts must move to a new version. +2. Public API changed. +3. Integration setup changed in a way consumers need through a new published version. +4. Release workflow intentionally publishes a new milestone. + +Tag is usually not required when: + +1. Only documentation changed. +2. Only `.github/` workflow or agent files changed. +3. Only internal process or repo maintenance changed. +4. Only Dependabot updated CI tooling and no release milestone is intended. + +Borderline cases: + +1. Publishing config changed: tag only if you intentionally want a new releasable artifact. +2. Docs + code changed: decide based on whether shipped SDK behavior changed. +3. Refactor-only code change: tag only if published artifacts or runtime behavior changed, or if an intentional release was requested. + +Decision rule: + +1. Merge to `main` is about integration. +2. Tagging is about releasing a version. +3. Do not conflate the two.