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
This commit is contained in:
William Valentin
428
CONTRIBUTING.md
Normal file
428
CONTRIBUTING.md
Normal file
@@ -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.*
|
||||
Reference in New Issue
Block a user