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
50
.github/copilot-instructions.md
vendored
Normal file
50
.github/copilot-instructions.md
vendored
Normal file
@@ -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?
|
||||
27
.rules
Normal file
27
.rules
Normal file
@@ -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
|
||||
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.*
|
||||
@@ -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.
|
||||
43
README.md
43
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
|
||||
|
||||
|
||||
25
docs/README.md
Normal file
25
docs/README.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user