docs: Add comprehensive locking mechanisms guide

[jamengual]

Summary

This PR adds comprehensive documentation for Atlantis's locking mechanisms, providing the definitive reference for understanding how locks prevent race conditions and ensure safe concurrent Terraform operations.

Documentation Overview

The guide documents all three lock types:

1. Project Locks (Database-Persisted)

   • Prevents concurrent plan/apply on same project+workspace
   • Survives server restarts
   • Key format: {repo}/{path}/{workspace}

2. Working Directory Locks (In-Memory)

   • Prevents concurrent filesystem operations
   • Automatic cleanup via defer
   • Key format: {repo}/{pullNum}/{workspace}/{path}

3. Apply Command Locks (Global)

   • System-wide apply control
   • Emergency maintenance capability

What's Included

• ✅ Architecture deep-dive with code references
• ✅ Complete workflow diagrams (plan/apply flows)
• ✅ Troubleshooting guide with common errors
• ✅ Error message dictionary with resolutions
• ✅ Best practices with DO/DON'T examples
• ✅ Historical context (PR docs(adr): Project Locks 0002 #3345, issues Unexpected change in locking behaviour #5722, Workspace (default) lock creation for no apparent reason #2200)
• ✅ Developer reference with testing patterns
• ✅ Database implementation details (BoltDB/Redis)

Why This Documentation?

Current state:

• Locking behavior scattered across code comments
• Users struggle with "workspace locked" errors
• No single reference for lock interactions
• Historical context (PR docs(adr): Project Locks 0002 #3345 ADR) not easily accessible

This guide provides:

• Single authoritative reference
• Quick error resolution lookup
• Understanding of lock hierarchy
• Context for ongoing improvements

File Location

ATLANTIS_LOCKING_COMPREHENSIVE_GUIDE.md (root directory)

Alternative locations to consider:

• docs/locking-mechanisms.md
• docs/architecture/locking.md

Open to suggestions on best location.

Related

• ADR docs(adr): Project Locks 0002 #3345 - Locking Architecture Decision
• Issue Unexpected change in locking behaviour #5722 - Lock isolation by project name
• Issue Workspace (default) lock creation for no apparent reason #2200 - Default workspace bottleneck
• PR feat: Add logic for project name into lock #4192 - Add ProjectName to locks
• PR fix: restore unlock comment functionality by removing premature lock deletion #5790 - Add path to working dir locks

Test Plan

• Documentation accuracy verified against codebase
• All code references include correct file paths and line numbers
• Error messages match actual implementation
• Workflows tested against current behavior

🤖 Generated with Claude Code