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 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

# 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

# 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

# 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

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

# 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
• FMF Testing: FMF Documentation
• osbuild: 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!