docs: consolidate and clean up documentation

- Remove redundant files: AGENTS.md, INSTRUCTIONS.yaml, instructions.mdc - Create comprehensive CONTRIBUTING.md with all development guidelines - Add simple documentation index at docs/README.md - Update main README to reference consolidated docs - Remove implementation notes and release summaries - Keep only essential, current documentation
2025-09-14 19:29:21 -07:00
parent 302a3d545c
commit 3fd7b1ca53
6 changed files with 555 additions and 179 deletions
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,50 @@
 Here’s a clean **developer guide in Markdown** format, ready to drop into your repo as `INSTRUCTIONS.md`. It captures your constraints, rules, and workflows in a human-readable but precise style.
 ---
 # Development Instructions
 ## Project Context
 * **UnitForge** is in **development**.
 * The project is **not in production**.
 * **No compatibility requirements** between major code changes.
 * Guiding principle: **Keep it small and simple**.
 ## Development Rules
 1. **Fix lint errors** – Code must always pass lint checks.
 2. **Keep code lean** – Avoid unnecessary abstractions; keep it direct.
 3. **Keep tests consistent** – All tests must pass; write tests for new code.
 4. **Remove legacy code** – Delete or refactor outdated code.
 5. **Use Makefile for services** – Prefer `make` targets to run and manage services.
 6. **Server** – Run the backend with **Uvicorn**.
 7. **Package management** – Use **uv** exclusively, never pip.
 ## Common Commands
 | Task                 | Command                    |
 | -------------------- | -------------------------- |
 | Setup environment    | `make setup-dev`           |
 | Run server           | `make server`              |
 | Run tests            | `make test`                |
 | Run tests (coverage) | `make test-cov`            |
 | Lint & format code   | `make lint && make format` |
 | Full dev cycle       | `make dev`                 |
 ## Style Guidelines
 * **Python**:
  * Follow **PEP 8**.
  * Use **type hints** consistently.
  * Format code with **Black**.
 * **Code quality**:
  * Avoid duplication.
  * Keep modules cohesive.
  * Minimize complexity.
 ---
 Would you like me to also add a **“Workflow Examples”** section (e.g. *how to add a new feature step-by-step*) to make onboarding even smoother for future contributors?
--- a/.rules
+++ b/.rules
@@ -0,0 +1,27 @@
 PROJECT: UnitForge
 STAGE: development
 PRODUCTION: false
 COMPATIBILITY: none
 PRINCIPLE: keep_small_simple
 RULE: fix_lint_errors
 RULE: keep_code_lean
 RULE: keep_tests_consistent
 RULE: remove_legacy_code
 RULE: use_makefile_services
 SERVER: uvicorn
 PACKAGE_MANAGER: uv
 CMD: make setup-dev
 CMD: make server
 CMD: make test
 CMD: make test-cov
 CMD: make lint && make format
 CMD: make dev
 STYLE: python_pep8
 STYLE: python_type_hints
 STYLE: python_formatter_black
 STYLE: code_no_duplication
 STYLE: code_high_cohesion
 STYLE: code_minimal_complexity
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,428 @@
 # Contributing to UnitForge
 Thank you for your interest in contributing to UnitForge! This guide will help you get started with development and understand our project workflow.
 ## 🏗️ Project Overview
 **UnitForge** is a comprehensive tool for creating, validating, and managing Linux systemd unit files.
 - **Stage**: Development
 - **Production**: Not in production
 - **Compatibility**: No backward compatibility requirements during development
 - **Principle**: Keep it small and simple
 ## 🚀 Quick Start
 ### Prerequisites
 - Python 3.11+
 - [uv](https://github.com/astral-sh/uv) package manager
 - Git
 ### Setup Development Environment
 ```bash
 # Clone the repository
 git clone <repository-url>
 cd unitforge
 # Quick setup (recommended)
 make setup-dev
 # Manual setup
 uv venv
 source .venv/bin/activate
 uv pip install -e ".[dev,web]"
 ```
 ### Essential Commands
 | Task | Command |
 |------|---------|
 | Setup environment | `make setup-dev` |
 | Run server | `make server` |
 | Run tests | `make test` |
 | Run tests with coverage | `make test-cov` |
 | Lint and format | `make lint && make format` |
 | Full dev cycle | `make dev` |
 ## 📋 Development Rules
 ### Core Principles
 1. **Fix lint errors** - Code must always pass lint checks
 2. **Keep code lean** - Avoid unnecessary abstractions; keep it direct
 3. **Keep tests consistent** - All tests must pass; write tests for new code
 4. **Remove legacy code** - Delete or refactor outdated code
 5. **Use Makefile for services** - Prefer `make` targets to run and manage services
 ### Technical Requirements
 - **Server**: uvicorn
 - **Package Manager**: uv (never use pip)
 - **Python Standard**: PEP 8
 - **Type Hints**: Required for all new code
 - **Formatter**: Black
 - **Code Quality**: No duplication, high cohesion, minimal complexity
 ## 🔄 Development Workflow
 ### 1. Setting Up for a New Feature
 ```bash
 # Update your local repository
 git pull origin main
 # Create a feature branch
 git checkout -b feature/your-feature-name
 # Set up development environment
 make setup-dev
 ```
 ### 2. Development Cycle
 ```bash
 # Make your changes...
 # Run the full development cycle
 make dev  # This runs: format + lint + test
 # Or run individually:
 make format  # Format code with Black
 make lint    # Run linting checks
 make test    # Run test suite
 ```
 ### 3. Testing Your Changes
 ```bash
 # Run specific tests
 make test
 # Run with coverage
 make test-cov
 # Test the web interface
 make server
 # Visit http://localhost:8000
 # Test CLI functionality
 ./unitforge-cli --help
 ```
 ### 4. Quality Checks
 Before committing, ensure all quality checks pass:
 ```bash
 # All-in-one quality check
 make dev
 # Individual checks
 make lint     # flake8, black --check, isort --check
 make format   # black, isort
 make test     # pytest
 ```
 ### 5. Submitting Changes
 ```bash
 # Add and commit your changes
 git add .
 git commit -m "feat: add amazing new feature"
 # Push your branch
 git push origin feature/your-feature-name
 # Create a pull request
 ```
 ## 🧪 Testing Guidelines
 ### Writing Tests
 - Place tests in the `tests/` directory
 - Use pytest for all testing
 - Follow the existing test patterns
 - Include both unit and integration tests
 ### Test Structure
 ```python
 def test_feature_behavior():
    """Test that feature behaves correctly."""
    # Arrange
    setup_test_data()
    # Act
    result = call_feature()
    # Assert
    assert result.is_valid()
 ```
 ### Running Tests
 ```bash
 # All tests
 make test
 # With coverage report
 make test-cov
 # Specific test file
 uv run pytest tests/test_specific.py -v
 # Watch mode (re-run on changes)
 make test-watch
 ```
 ## 🎨 Code Style
 ### Python Style Guidelines
 - **Follow PEP 8** strictly
 - **Use type hints** for all functions and methods
 - **Format with Black** (automatic via pre-commit)
 - **Sort imports** with isort (automatic via pre-commit)
 ### Example Code Style
 ```python
 from typing import Optional, List
 from pathlib import Path
 def process_unit_file(
    file_path: Path,
    validate: bool = True,
    options: Optional[List[str]] = None
 ) -> bool:
    """Process a systemd unit file.
    Args:
        file_path: Path to the unit file
        validate: Whether to validate the file
        options: Additional processing options
    Returns:
        True if processing succeeded
    Raises:
        FileNotFoundError: If the file doesn't exist
        ValidationError: If validation fails
    """
    if options is None:
        options = []
    # Implementation...
    return True
 ```
 ### Code Organization
 - **High cohesion**: Keep related functionality together
 - **Low coupling**: Minimize dependencies between modules
 - **Minimal complexity**: Prefer simple, readable code
 - **No duplication**: Extract common functionality
 ## 🏗️ Architecture Guidelines
 ### Project Structure
 ```
 unitforge/
 ├── backend/           # Python backend
 │   ├── app/          # FastAPI application
 │   ├── cli/          # CLI implementation
 │   └── requirements.txt
 ├── frontend/         # Web interface
 │   ├── static/       # CSS, JS, assets
 │   └── templates/    # HTML templates
 ├── tests/            # Test suite
 ├── scripts/          # Utility scripts
 └── docs/             # Documentation
 ```
 ### Adding New Features
 1. **Backend Features**: Add to `backend/app/`
 2. **CLI Features**: Add to `backend/cli/`
 3. **Templates**: Add to `backend/app/templates/`
 4. **Tests**: Add to `tests/`
 5. **Documentation**: Update relevant docs
 ### API Development
 - Use FastAPI for all API endpoints
 - Follow REST conventions
 - Include comprehensive error handling
 - Add API documentation with docstrings
 ## 🐳 Docker Development
 ### Docker Commands
 ```bash
 # Build containers
 make docker-build
 # Run development environment
 make docker-dev
 # Run production environment
 make docker-prod
 # Clean up
 make docker-clean
 ```
 ### Container Registry
 ```bash
 # Build and push to registry
 make registry-push
 # Login to registry
 make docker-login
 ```
 ## 🔧 Debugging
 ### Common Issues
 **Import Errors:**
 ```bash
 # Ensure you're in the virtual environment
 source .venv/bin/activate
 # Reinstall in development mode
 uv pip install -e ".[dev,web]"
 ```
 **Test Failures:**
 ```bash
 # Run tests with verbose output
 make test -v
 # Run specific failing test
 uv run pytest tests/test_failing.py::test_function -v
 ```
 **Linting Errors:**
 ```bash
 # Auto-fix formatting issues
 make format
 # Check what lint issues remain
 make lint
 ```
 ### Development Tools
 ```bash
 # Start development server with hot reload
 make server
 # Open interactive Python shell with project context
 uv run python
 # Run CLI in development mode
 ./unitforge-cli --help
 ```
 ## 📖 Documentation
 ### Updating Documentation
 - Update relevant documentation when adding features
 - Follow existing documentation patterns
 - Include code examples for new APIs
 - Test documentation examples
 ### Documentation Files
 - `README.md` - Main project documentation
 - `docs/ENVIRONMENT.md` - Environment configuration
 - `CONTRIBUTING.md` - This file
 - `docker/README.md` - Docker-specific documentation
 - `scripts/README.md` - Utility scripts documentation
 ## 🚀 Release Process
 ### Version Management
 UnitForge uses semantic versioning (SemVer):
 - `MAJOR.MINOR.PATCH`
 - Major: Breaking changes
 - Minor: New features
 - Patch: Bug fixes
 ### Pre-release Checklist
 - [ ] All tests pass (`make test`)
 - [ ] No linting errors (`make lint`)
 - [ ] Documentation updated
 - [ ] Version bumped in `pyproject.toml`
 - [ ] CHANGELOG updated
 ## 🤝 Community Guidelines
 ### Code of Conduct
 - Be respectful and inclusive
 - Help others learn and contribute
 - Focus on constructive feedback
 - Celebrate different perspectives
 ### Getting Help
 1. **Check existing documentation** in `docs/`
 2. **Search existing issues** on GitHub
 3. **Run the demo** with `./demo.sh`
 4. **Ask questions** in GitHub discussions
 5. **Report bugs** with detailed reproduction steps
 ### Issue Reporting
 When reporting bugs, please include:
 - Operating system and version
 - Python version
 - uv version
 - Steps to reproduce
 - Expected vs actual behavior
 - Relevant log output
 ### Feature Requests
 For feature requests:
 - Check existing issues for duplicates
 - Describe the use case clearly
 - Provide examples if possible
 - Consider implementation complexity
 - Align with project principles
 ## 🔗 Useful Links
 - **Main Repository**: [GitHub Repository URL]
 - **Issue Tracker**: [GitHub Issues URL]
 - **API Documentation**: http://localhost:8000/api/docs (when running)
 - **systemd Documentation**: https://systemd.io/
 ## 🎯 Next Steps
 1. **Set up your development environment** with `make setup-dev`
 2. **Run the tests** to ensure everything works: `make test`
 3. **Try the web interface**: `make server`
 4. **Explore the CLI**: `./unitforge-cli --help`
 5. **Read the code** in `backend/app/` to understand the architecture
 6. **Look at existing tests** in `tests/` for examples
 7. **Check open issues** for contribution opportunities
 Welcome to the UnitForge community! 🚀
 ---
 *This guide is a living document. Please help keep it up-to-date as the project evolves.*
--- a/ENVIRONMENT_IMPLEMENTATION.md
+++ b/ENVIRONMENT_IMPLEMENTATION.md
@@ -1,161 +0,0 @@
 # Environment Variable Implementation Summary
 This document summarizes the implementation of environment variable support for UnitForge, making the application configurable without code changes.
 ## Overview
 The implementation adds comprehensive environment variable support to UnitForge, allowing configuration of:
 - Application metadata (name, version, description)
 - External links (GitHub, documentation, bug reports)
 - Server settings (host, port, debug mode)
 - CORS configuration
 - Contact information
 ## Files Modified
 ### Core Configuration
 - **`backend/app/core/config.py`** - New configuration module with Settings class
 - **`.env.example`** - Template for environment variables
 - **`docs/ENVIRONMENT.md`** - Comprehensive documentation
 ### Application Integration
 - **`backend/app/main.py`** - Updated to use settings and inject template context
 - **`backend/cli/__init__.py`** - Updated to use configurable app name and version
 - **`backend/__init__.py`** - Updated to use environment variables for metadata
 ### Templates
 - **`frontend/templates/index.html`** - Updated to use template variables
 - **`frontend/templates/templates.html`** - Updated to use template variables  
 - **`frontend/templates/editor.html`** - Updated to use template variables
 ### Build and Development
 - **`pyproject.toml`** - Added python-dotenv dependency
 - **`docker-compose.yml`** - Added env_file support to all services
 - **`Makefile`** - Added .env file creation during setup
 - **`check-uv.sh`** - Updated to use environment variable for GitHub URL
 ## Key Features
 ### 1. Configuration Management
 ```python
 from app.core.config import settings
 # Access configuration
 print(settings.app_name)
 print(settings.github_url)
 ```
 ### 2. Template Integration
 HTML templates automatically receive configuration variables:
 ```html
 <title>{{ app_name }} - Page Title</title>
 <a href="{{ github_url }}">GitHub</a>
 ```
 ### 3. Environment File Support
 - Automatic loading of `.env` files using python-dotenv
 - Fallback to default values when variables are not set
 - Docker Compose integration
 ### 4. Development Workflow
 - `make setup-dev` automatically creates `.env` from template
 - Environment variables override defaults
 - No code changes needed for different deployments
 ## Configuration Variables
 ### Application Settings
 ```bash
 APP_NAME=UnitForge
 APP_VERSION=1.0.0
 APP_DESCRIPTION=Create, validate, and manage systemd unit files
 ```
 ### External Links
 ```bash
 GITHUB_URL=https://github.com/will666/unitforge
 DOCUMENTATION_URL=https://unitforge.readthedocs.io/
 BUG_REPORTS_URL=https://github.com/will666/unitforge/issues
 ```
 ### Server Configuration
 ```bash
 HOST=0.0.0.0
 PORT=8000
 DEBUG=false
 CORS_ORIGINS=*
 ```
 ### Contact Information
 ```bash
 CONTACT_EMAIL=contact@unitforge.dev
 ```
 ## Benefits
 1. **Deployment Flexibility** - Same codebase works across environments
 2. **Customization** - Easy branding and configuration changes
 3. **Security** - Sensitive values can be set via environment
 4. **Container Ready** - Full Docker and Kubernetes support
 5. **Developer Friendly** - Automatic setup and clear documentation
 ## Usage Examples
 ### Development Override
 ```bash
 # Temporary override for testing
 GITHUB_URL="https://github.com/myorg/fork" python -m uvicorn backend.app.main:app
 ```
 ### Production Deployment
 ```bash
 # Production .env file
 APP_NAME=UnitForge Production
 DEBUG=false
 HOST=0.0.0.0
 PORT=80
 GITHUB_URL=https://github.com/mycompany/unitforge
 SECRET_KEY=production-secret-key
 ```
 ### Docker Deployment
 ```yaml
 # docker-compose.yml automatically loads .env
 services:
  unitforge:
    env_file: .env
    environment:
      - DEBUG=false  # Override specific values
 ```
 ## Testing
 All changes have been validated:
 - ✅ Configuration loads correctly with defaults
 - ✅ Environment variables override defaults
 - ✅ Templates render with injected variables
 - ✅ CLI shows configured app name and version
 - ✅ Docker Compose loads environment files
 - ✅ No linting errors or diagnostics issues
 ## Migration Path
 For existing deployments:
 1. Copy `.env.example` to `.env`
 2. Customize values as needed
 3. No code changes required
 4. Templates automatically use new variables
 ## Future Enhancements
 Potential additions:
 - Database configuration via environment
 - Email service configuration
 - Logging configuration
 - Feature flags
 - API rate limiting settings
 - Theme customization variables
 ## Conclusion
 This implementation provides a robust, flexible configuration system that follows modern application development best practices while maintaining backward compatibility and ease of use.
--- a/README.md
+++ b/README.md
@@ -460,8 +460,18 @@ UnitForge uses [uv](https://github.com/astral-sh/uv) for blazing-fast Python pac
 | `make clean` | Clean cache files | Standard |
 | `make status` | Show project status | Standard |
-## 📚 systemd Documentation References
+## 📚 Documentation
 ### 📖 Complete Documentation
 For comprehensive guides and references, see the [**Documentation Index**](docs/README.md):
 - **[User Guide](docs/README.md#user-documentation)** - Installation, usage, and configuration
 - **[Developer Guide](CONTRIBUTING.md)** - Development setup and contribution workflow
 - **[Environment Configuration](docs/ENVIRONMENT.md)** - Complete environment variable reference
 - **[Docker Setup](docker/README.md)** - Container development and deployment
 - **[Scripts & Utilities](scripts/README.md)** - Development tools and color utilities
 ### 🔗 External References
 - [systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) - Unit configuration
 - [systemd.service(5)](https://www.freedesktop.org/software/systemd/man/systemd.service.html) - Service units
 - [systemd.timer(5)](https://www.freedesktop.org/software/systemd/man/systemd.timer.html) - Timer units
@@ -470,25 +480,22 @@ UnitForge uses [uv](https://github.com/astral-sh/uv) for blazing-fast Python pac
 ## 🤝 Contributing
 **New contributors**: Please see the [**Contributing Guide**](CONTRIBUTING.md) for complete development setup and workflow instructions.
 ### Quick Contributing Steps
 1. Fork the repository
-2. Create a feature branch: `git checkout -b feature/amazing-feature`
+2. Set up development environment: `make setup-dev`
-3. Set up development environment: `make setup-dev`
+3. Create a feature branch: `git checkout -b feature/amazing-feature`
-4. Make your changes
+4. Make your changes and add tests
-5. Add tests for new functionality
+5. Run quality checks: `make dev` (format + lint + test)
-6. Ensure quality checks pass: `make check-all`
+6. Commit and push your changes
-7. Commit your changes: `git commit -m 'Add amazing feature'`
+7. Submit a pull request
 8. Push to the branch: `git push origin feature/amazing-feature`
 9. Submit a pull request
-### Contribution Guidelines
+### Key Guidelines
-
+- **Development Setup**: Use [Contributing Guide](CONTRIBUTING.md) for consistent environment
- **Setup**: Use `make setup-dev` for consistent environment (uv required)
+- **Quality Assurance**: All code must pass `make dev` (format, lint, test)
- **Quality**: Run `make check-all` before committing
+- **Documentation**: Update relevant docs for new features
- **Tests**: Write tests for new features (`make test-cov`)
+- **Testing**: Write tests for new functionality
 - **Style**: Code is auto-formatted with pre-commit hooks
 - **Type Safety**: Add type hints for Python code
 - **Documentation**: Update docs for API changes
 - **Performance**: Built for uv - no pip fallbacks
 ## 📄 License
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,25 @@
 # UnitForge Documentation
 ## 📚 Documentation
 | Document | Description |
 |----------|-------------|
 | [**Main README**](../README.md) | Project overview, installation, and usage |
 | [**Contributing Guide**](../CONTRIBUTING.md) | Development setup and workflow |
 | [**Environment Configuration**](ENVIRONMENT.md) | Environment variable reference |
 | [**Docker Setup**](../docker/README.md) | Container development |
 | [**Scripts & Utilities**](../scripts/README.md) | Development tools |
 ## 🚀 Quick Start
 **New users**: Start with the [Main README](../README.md)
 **Contributors**: Follow the [Contributing Guide](../CONTRIBUTING.md)
 **Configuration**: See [Environment Variables](ENVIRONMENT.md)
 ## 🔗 External References
 - [systemd documentation](https://systemd.io/)
 - [FastAPI documentation](https://fastapi.tiangolo.com/)
 - [uv documentation](https://github.com/astral-sh/uv)