From 3fd7b1ca53ba05b8c0e72bc8bc71f13b51f7f32a Mon Sep 17 00:00:00 2001 From: William Valentin Date: Sun, 14 Sep 2025 19:29:21 -0700 Subject: [PATCH] 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 --- .github/copilot-instructions.md | 50 ++++ .rules | 27 ++ CONTRIBUTING.md | 428 ++++++++++++++++++++++++++++++++ ENVIRONMENT_IMPLEMENTATION.md | 161 ------------ README.md | 43 ++-- docs/README.md | 25 ++ 6 files changed, 555 insertions(+), 179 deletions(-) create mode 100644 .github/copilot-instructions.md create mode 100644 .rules create mode 100644 CONTRIBUTING.md delete mode 100644 ENVIRONMENT_IMPLEMENTATION.md create mode 100644 docs/README.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..9448e81 --- /dev/null +++ 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? diff --git a/.rules b/.rules new file mode 100644 index 0000000..67e24c4 --- /dev/null +++ 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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..84646b6 --- /dev/null +++ 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 +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.* diff --git a/ENVIRONMENT_IMPLEMENTATION.md b/ENVIRONMENT_IMPLEMENTATION.md deleted file mode 100644 index 4adaf05..0000000 --- a/ENVIRONMENT_IMPLEMENTATION.md +++ /dev/null @@ -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 -{{ app_name }} - Page Title -GitHub -``` - -### 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. \ No newline at end of file diff --git a/README.md b/README.md index 3b0355a..28f0bcb 100644 --- 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` -3. Set up development environment: `make setup-dev` -4. Make your changes -5. Add tests for new functionality -6. Ensure quality checks pass: `make check-all` -7. Commit your changes: `git commit -m 'Add amazing feature'` -8. Push to the branch: `git push origin feature/amazing-feature` -9. Submit a pull request +2. Set up development environment: `make setup-dev` +3. Create a feature branch: `git checkout -b feature/amazing-feature` +4. Make your changes and add tests +5. Run quality checks: `make dev` (format + lint + test) +6. Commit and push your changes +7. Submit a pull request -### Contribution Guidelines - -- **Setup**: Use `make setup-dev` for consistent environment (uv required) -- **Quality**: Run `make check-all` before committing -- **Tests**: Write tests for new features (`make test-cov`) -- **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 +### Key Guidelines +- **Development Setup**: Use [Contributing Guide](CONTRIBUTING.md) for consistent environment +- **Quality Assurance**: All code must pass `make dev` (format, lint, test) +- **Documentation**: Update relevant docs for new features +- **Testing**: Write tests for new functionality ## 📄 License diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..74d7bf6 --- /dev/null +++ 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)