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:

Add .claude/ to .gitignore (preferred)
Perform version updates manually when script fails

Manual Steps

# 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:

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

# 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:

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