deb-bootc-image-builder/docs/CONTRIBUTING.md

# Contributing to deb-bootc-image-builder

Thank you for your interest in contributing to deb-bootc-image-builder! This document provides guidelines and information for contributors.

## 🏗️ Repository Structure

This repository follows the standard structure used by [osbuild/bootc-image-builder](https://github.com/osbuild/bootc-image-builder) and other osbuild projects:

```
.
├── .fmf/                    # FMF (Flexible Metadata Format) testing framework
│   ├── config              # FMF configuration
│   ├── plans/              # Test plans
│   ├── stories/            # User stories
│   └── features/           # Feature specifications
├── .github/                 # GitHub workflows and templates
│   └── workflows/          # CI/CD workflows
├── .tekton/                 # Tekton CI/CD pipelines
├── bib/                     # Main Go application (bootc-image-builder)
│   ├── cmd/                # Command-line interfaces
│   ├── internal/           # Internal packages
│   └── data/               # Static data files
├── bin/                     # Binary outputs and tools
├── containerfiles/          # Container definitions
├── devel/                   # Development tools and documentation
├── docs/                    # Project documentation
├── osbuild-stages/          # Custom osbuild stages for Debian
├── ostree-workspace/        # OSTree development workspace
├── plans/                   # Test plans and specifications
├── recipes/                 # YAML recipe files for OS builds
├── scripts/                 # Utility scripts organized by function
│   ├── build-scripts/      # Build and compilation scripts
│   ├── integration-scripts/ # Integration and testing scripts
│   ├── test-scripts/       # Test execution scripts
│   └── test-files/         # Test-related files
├── test/                    # Test files and utilities
│   ├── integration/        # Integration tests
│   ├── unit/               # Unit tests
│   ├── performance/        # Performance tests
│   └── test-images/        # Test image files
├── Containerfile            # Main container definition
├── Containerfile.particle-os # Particle OS specific container
├── Makefile                 # Build and development tasks
├── README.md                # Project documentation
└── CHANGELOG.md             # Change history
```

## 📁 Directory Organization

### **Core Application (`bib/`)**
- **`cmd/`**: Command-line interfaces and entry points
- **`internal/`**: Internal packages and implementation
- **`data/`**: Static data files and resources

### **Scripts (`scripts/`)**
- **`build-scripts/`**: Build, compilation, and deployment scripts
- **`integration-scripts/`**: Integration testing and workflow scripts
- **`test-scripts/`**: Test execution and validation scripts
- **`test-files/`**: Test-related configuration and data files

### **Testing (`test/`)**
- **`integration/`**: End-to-end integration tests
- **`unit/`**: Unit tests for individual components
- **`performance/`**: Performance and benchmark tests
- **`test-images/`**: Test image files and artifacts

### **Documentation (`docs/`)**
- **User guides**: How to use the tool
- **Developer guides**: How to contribute and develop
- **Architecture docs**: System design and implementation details

## 🧪 Testing Framework

This project uses the **FMF (Flexible Metadata Format)** testing framework, which is the standard for osbuild projects:

- **`.fmf/plans/`**: Test plans and specifications
- **`.fmf/stories/`**: User stories and requirements
- **`.fmf/features/`**: Feature specifications and tests

## 🚀 Development Workflow

### **1. Setting Up Development Environment**
```bash
# Clone the repository
git clone https://github.com/your-username/deb-bootc-image-builder.git
cd deb-bootc-image-builder

# Install Go dependencies
cd bib
go mod download
cd ..

# Install Python dependencies for testing
pip install -r test/requirements.txt
```

### **2. Running Tests**
```bash
# Run all tests
pytest test/

# Run specific test categories
pytest test/unit/
pytest test/integration/
pytest test/performance/

# Run with FMF
fmf run --all
```

### **3. Building the Application**
```bash
# Build from source
cd bib
go build -o particle-os cmd/builder/main.go
cd ..

# Use Makefile targets
make build
make test
make clean
```

## 📝 Code Style and Standards

### **Go Code**
- Follow Go standard formatting (`go fmt`)
- Use `golangci-lint` for linting
- Follow Go naming conventions
- Include proper error handling

### **Python Code**
- Follow PEP 8 style guidelines
- Use type hints where appropriate
- Include docstrings for functions and classes
- Run `flake8` and `pylint` for code quality

### **Shell Scripts**
- Use `bash` with `set -euo pipefail`
- Follow shell script best practices
- Include proper error handling and cleanup

## 🔧 Adding New Features

### **1. Create Feature Branch**
```bash
git checkout -b feature/your-feature-name
```

### **2. Implement Feature**
- Add code in appropriate directories
- Include tests for new functionality
- Update documentation as needed

### **3. Test Your Changes**
```bash
# Run relevant tests
pytest test/unit/test_your_feature.py
pytest test/integration/test_your_feature.py

# Run full test suite
make test
```

### **4. Submit Pull Request**
- Create descriptive PR title and description
- Reference any related issues
- Ensure all tests pass
- Request review from maintainers

## 🐛 Reporting Issues

When reporting issues, please include:

1. **Clear description** of the problem
2. **Steps to reproduce** the issue
3. **Expected vs actual behavior**
4. **Environment details** (OS, Go version, etc.)
5. **Relevant logs** and error messages

## 📚 Additional Resources

- **Project Documentation**: See `docs/` directory
- **Original Project**: [osbuild/bootc-image-builder](https://github.com/osbuild/bootc-image-builder)
- **FMF Testing**: [FMF Documentation](https://fmf.readthedocs.io/)
- **osbuild**: [osbuild.org](https://www.osbuild.org)

## 🤝 Getting Help

- **GitHub Issues**: For bug reports and feature requests
- **GitHub Discussions**: For questions and general discussion
- **Matrix**: Join #image-builder on fedoraproject.org

Thank you for contributing to deb-bootc-image-builder!