From 99d9328fb4abe099e2f0372b921b9f6d3b702518 Mon Sep 17 00:00:00 2001
From: Leo Miranda <leobmiranda@gmail.com>
Date: Sun, 25 Jan 2026 19:48:02 +0000
Subject: [PATCH] Add
 "lessons/sprints/v400-release---wiki-workflow-and-versioning-patterns"

---
 ...wiki-workflow-and-versioning-patterns.-.md | 150 ++++++++++++++++++
 1 file changed, 150 insertions(+)
 create mode 100644 lessons%2Fsprints%2Fv400-release---wiki-workflow-and-versioning-patterns.-.md

diff --git a/lessons%2Fsprints%2Fv400-release---wiki-workflow-and-versioning-patterns.-.md b/lessons%2Fsprints%2Fv400-release---wiki-workflow-and-versioning-patterns.-.md
new file mode 100644
index 0000000..3953858
--- /dev/null
+++ b/lessons%2Fsprints%2Fv400-release---wiki-workflow-and-versioning-patterns.-.md
@@ -0,0 +1,150 @@
+# Lessons Learned: v4.0.0 Release
+
+**Date:** 2026-01-25
+**Version:** v4.0.0
+**Scope:** data-platform plugin release + wiki workflow establishment
+
+---
+
+## Lesson 1: Wiki-Based Change Proposal Workflow
+
+### Context
+Needed to document the v4.0.0 implementation plan and preserve planning rationale beyond issue creation.
+
+### Pattern Established
+```
+Wiki Structure:
+- "Change VXX.X.X: Proposal" - Original architecture/design reference
+- "Change VXX.X.X: Proposal (Implementation N)" - Specific implementation plan
+
+Tags for Proposals:
+> **Type:** Change Proposal
+> **Version:** VXX.X.X
+> **Status:** Pending | In Progress | Implemented
+> **Date:** YYYY-MM-DD
+
+Tags for Implementations:
+> **Type:** Change Proposal Implementation
+> **Version:** VXX.X.X
+> **Status:** Implemented
+> **Date:** YYYY-MM-DD
+> **Origin:** [link to proposal]
+```
+
+### Benefit
+- Separates planning docs from project documentation
+- Creates traceability chain: Proposal → Implementation → Issues → Lessons
+- Supports multiple implementations per proposal
+
+---
+
+## Lesson 2: Release Script Requires Clean Working Directory
+
+### Problem
+`./scripts/release.sh 4.0.0` failed because `.claude/` directory (local settings) was untracked.
+
+### Solution
+Either:
+1. Add `.claude/` to `.gitignore` (preferred)
+2. Perform version updates manually when script fails
+
+### Manual Steps
+```bash
+# 1. Update CHANGELOG.md: [Unreleased] → [X.Y.Z] - YYYY-MM-DD
+# 2. Update README.md title
+# 3. Update marketplace.json version
+# 4. Commit and tag
+```
+
+### Prevention
+Add `.claude/` to `.gitignore` in the repository.
+
+---
+
+## Lesson 3: Protected Branch Requires PR for Version Bumps
+
+### Problem
+Direct push to `development` branch failed with "Not allowed to push to protected branch".
+
+### Solution
+Even version bump commits need a PR:
+```bash
+git checkout -b chore/release-vX.Y.Z
+git push -u origin chore/release-vX.Y.Z
+# Create PR via API or web
+```
+
+### Note
+This is correct behavior - all changes should go through PR review.
+
+---
+
+## Lesson 4: Git Tag Timing Matters
+
+### Problem
+Created tag before PR merge, pointing to wrong commit. Then tag already existed when trying to recreate.
+
+### Solution
+```bash
+# Delete local tag
+git tag -d vX.Y.Z
+
+# Create tag at merge commit (after PR merge)
+git tag -a vX.Y.Z -m "Release vX.Y.Z - description"
+
+# Push tag
+git push origin vX.Y.Z
+```
+
+### Prevention
+Always create tags AFTER the PR is merged, pointing to the merge commit.
+
+---
+
+## Lesson 5: MCP Tool Gap - No PR Creation
+
+### Problem
+Gitea MCP server has `list_pull_requests`, `get_pull_request`, `create_pr_review`, but no `create_pull_request` tool.
+
+### Workaround
+Used curl with Gitea API directly:
+```bash
+curl -X POST "https://gitea.example.com/api/v1/repos/owner/repo/pulls" \
+  -H "Authorization: token $GITEA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "...", "head": "branch", "base": "development", "body": "..."}'
+```
+
+### Future Improvement
+Consider adding `create_pull_request` tool to Gitea MCP server.
+
+---
+
+## Lesson 6: Version Naming Convention
+
+### Pattern
+Wiki pages use zero-padded version format: `V04.0.0` (capital V, two-digit major)
+
+### Examples
+- `Change V04.0.0: Proposal` (not `v4.0.0`)
+- `Change V03.2.0: Proposal`
+
+### Reason
+Ensures proper alphabetical sorting in wiki page list.
+
+---
+
+## Summary
+
+| Lesson | Category | Impact |
+|--------|----------|--------|
+| Wiki workflow for proposals | Process | High - establishes documentation pattern |
+| Release script clean dir | Tooling | Low - workaround available |
+| Protected branch PRs | Process | Normal - correct behavior |
+| Tag after merge | Git | Medium - prevents tag conflicts |
+| No PR creation MCP tool | Tooling | Low - API workaround works |
+| Version naming V0X.X.X | Convention | Medium - wiki organization |
+
+
+---
+**Tags:** versioning, wiki, release-workflow, git-tags, protected-branches, mcp-tools, data-platform
\ No newline at end of file