6.0 KiB

Raw Blame History

.patch Directory - Permanent Documentation Repository

⚠️ CRITICAL: DO NOT DELETE THIS FOLDER

This directory maintains permanent, immutable documentation of all implemented PR changes across the entire project.

Purpose

The .patch/ directory serves as:

Historical Record: Complete diff documentation for every PR
Code Review Reference: Quick access to what was changed and why
Permanent Archive: Backup of all implementation details
Development Audit Trail: Track of all project modifications

Structure

Each PR gets its own numbered subdirectory:

.patch/
├── .gitkeep                 # Folder protection marker
├── 573/                     # PR #573: Agent Schema Validation
│   ├── agent.js.573.diff.txt
│   ├── test-agent-schema.js.573.diff.txt
│   └── patch.573.txt
├── 586/                     # PR #586: AICockpit IDE Support
│   ├── bmad.js.586.diff.txt
│   ├── eslint.config.mjs.586.diff.txt
│   ├── ide-setup.js.586.diff.txt
│   ├── install.config.yaml.586.diff.txt
│   ├── package-lock.json.586.diff.txt
│   ├── package.json.586.diff.txt
│   └── patch.586.txt
├── 629/                     # PR #629: Manifest Update Feature
│   ├── bmad.js.629.diff.txt
│   ├── installer.js.629.diff.txt
│   ├── package.json.629.diff.txt
│   └── patch.629.txt
└── 633/                     # PR #633: INIT_CWD Default Directory
    ├── bmad.js.633.diff.txt
    ├── cli.js.633.diff.txt
    ├── installer.js.633.diff.txt
    ├── main.js.633.diff.txt
    ├── patch.633.txt
    ├── upgrader.js.633.diff.txt
    └── web-builder.js.633.diff.txt

Protection Mechanisms

1. Git Tracking

All .patch files are committed to git
.patch/.gitkeep ensures folder is always tracked
Cannot be accidentally lost or ignored

2. Pre-commit Hook

.git/hooks/pre-commit prevents deletion of .patch files
Automatically warns if .patch files are being removed
Blocks commits that would delete .patch folder

3. Git Attributes

.gitattributes ensures proper line ending handling
Marks patch files with specific merge strategies
Prevents accidental modifications during merges

4. Documentation

.PATCH-PROTECTION-POLICY.md - Comprehensive protection policy
.patch/README.md - This file
Clear guidelines for all developers

Important Rules

❌ NEVER DO:

Delete .patch folder
```
rm -rf .patch  # ❌ FORBIDDEN
```

Add .patch to .gitignore

echo ".patch/" >> .gitignore  # ❌ FORBIDDEN

Modify or remove patch files
```
rm .patch/573/*  # ❌ FORBIDDEN
```
Force push without .patch
```
git push -f  # ❌ MIGHT LOSE .patch
```

✅ SAFE OPERATIONS:

Add new PR diffs

# After PR implementation, add to .patch/[PR-NUMBER]/
git add .patch/[number]/

Review patch files

cat .patch/573/patch.573.txt
diff .patch/586/bmad.js.586.diff.txt

Reference old changes
```
grep -r "INIT_CWD" .patch/633/
```

Recovery Procedures

If .patch Folder Is Accidentally Deleted

Immediate Recovery:
```
git checkout HEAD -- .patch/
```
From Specific Commit:
```
git checkout 946521dc -- .patch/
```

From Feature Branch:

git checkout feature/branch-name -- .patch/633/

If .patch Is Added to .gitignore

Remove from .gitignore:

grep -v "^\.patch" .gitignore > .gitignore.tmp
mv .gitignore.tmp .gitignore
git add .gitignore

Restore .patch tracking:

git rm --cached .gitignore
git add .gitignore .patch/

For Developers

When Adding New PRs

Create feature branch for implementation

After changes, generate diffs:

mkdir -p .patch/[PR-NUMBER]
git diff main HEAD -- [file] > .patch/[PR-NUMBER]/[file].diff.txt

Create comprehensive summary:

cat > .patch/[PR-NUMBER]/patch.[PR-NUMBER].txt << EOF
=== PR #[NUMBER]: [FEATURE NAME] ===

DESCRIPTION:
[implementation details]

COMMIT SHA: [sha]
BRANCH: [branch-name]
...
EOF

Commit to git:

git add .patch/[PR-NUMBER]/
git commit -m "docs(patch): add comprehensive diffs for PR #[NUMBER]"

For Maintainers

Before Merging PRs

Check if corresponding .patch/[PR-NUMBER]/ exists
Verify all modified files have diffs
Review comprehensive patch documentation
Ensure .patch folder is in merge commit

During Release

Verify .patch directory is included
Test that .patch is accessible in release
Document any new PR diffs added

Git Configuration

To ensure .patch is never accidentally removed, configure git:

# Prevent accidental deletion
git config core.protectNTFS true
git config core.safeCRLF warn

# Ensure proper line endings
git config core.autocrlf true

# Never auto-clean .patch
git config clean.requireForce true

Commits Protecting .patch

This folder is protected by these commits:

946521dc - chore: add all .patch directories and protection policy to main
97f9816b - chore: restore .patch/633 diffs to main branch
bee1e1a1 - docs(patch): add comprehensive diffs for PR #633
9f015e31 - docs(patch): add comprehensive diffs for PR #629

.PATCH-PROTECTION-POLICY.md - High-level protection policy
.gitattributes - Git file handling rules
.git/hooks/pre-commit - Pre-commit protection hook
.patch/.gitkeep - Folder tracking marker

Questions or Issues?

If you encounter issues with .patch folder:

Check .PATCH-PROTECTION-POLICY.md for detailed guidance
Review .git/hooks/pre-commit for protection mechanisms
Refer to "Recovery Procedures" section above
Contact team lead before making changes

Last Updated: October 26, 2025
Protection Status: ACTIVE AND PERMANENT
Critical Level: MAXIMUM

6.0 KiB Raw Blame History