mirror-get-aurora-dev-iso/CONTRIBUTING.md

Contributing to Aurora ISO Builder

Thank you for your interest in contributing to Aurora ISO Builder! This guide will help you get started with contributing to the project.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Making Changes
• Testing
• Submitting Changes
• Style Guide
• Resources

Code of Conduct

This project follows the Universal Blue Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

Before you begin, ensure you have the following tools installed:

• Git: Version control
• Pre-commit: For running validation hooks
• Bash: For running scripts

Installation

# Install pre-commit
pip install pre-commit

# Clone the repository
git clone https://github.com/ublue-os/aurora-iso.git
cd aurora-iso

# Install pre-commit hooks
pre-commit install

Development Setup

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/aurora-iso.git
   cd aurora-iso
   

3. Add upstream remote:

   git remote add upstream https://github.com/ublue-os/aurora-iso.git
   

4. Install pre-commit hooks:

   pre-commit install
   

Making Changes

Branch Naming

Create a descriptive branch name:

• feat/add-new-feature - For new features
• fix/bug-description - For bug fixes
• docs/update-readme - For documentation changes
• chore/update-deps - For maintenance tasks

Commit Messages

We use Conventional Commits for all commit messages:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• chore: Maintenance tasks
• refactor: Code refactoring
• test: Adding or updating tests
• ci: CI/CD changes

Examples:

feat: add support for custom kernel arguments

fix: correct Anaconda profile partitioning scheme

docs: update README with new ISO variants

chore: update pre-commit hooks to v5.0.0

Attribution Footer

If using AI assistance, include an attribution footer:

feat: improve ISO configuration script

Assisted-by: Claude 3.5 Sonnet via Zed AI

Testing

Local Validation

Always validate your changes before committing:

# Run all pre-commit hooks
pre-commit run --all-files

# Test ISO configuration script syntax
bash -n iso_files/configure_iso_anaconda.sh
bash -n iso_files/build.sh

ISO Build Testing

ISO builds are automatically triggered on pull requests. The workflow will:

1. Build ISOs for all configured flavors
2. Generate checksums
3. Upload artifacts to GitHub

You can download and test the generated ISOs from the GitHub Actions artifacts.

Manual Testing

To manually test the ISO configuration script:

# Validate bash syntax
bash -n iso_files/configure_iso_anaconda-webui.sh

Submitting Changes

Before Submitting

1. Sync with upstream:

   git fetch upstream
   git rebase upstream/main
   

2. Run validation:

   pre-commit run --all-files
   bash -n iso_files/configure_iso_anaconda.sh
   bash -n iso_files/build.sh
   

3. Test your changes: Ensure the ISO builds successfully in GitHub Actions

Pull Request Process

1. Push your changes:

   git push origin your-branch-name
   

2. Create a Pull Request on GitHub with:

   • Clear title using conventional commit format
   • Detailed description of changes
   • Link to related issues (if applicable)
   • Screenshots or logs (if relevant)

3. Wait for CI checks to complete:

   • Pre-commit hooks
   • ISO build (if workflow files changed)

4. Address review feedback if requested

5. Squash commits if requested by maintainers

Pull Request Template

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Maintenance/chore

## Testing
- [ ] Ran pre-commit hooks
- [ ] Tested ISO configuration script syntax
- [ ] ISO builds successfully in GitHub Actions

## Related Issues
Closes #123

## Additional Notes
Any additional context or notes for reviewers.

Style Guide

Shell Scripts

• Use #!/usr/bin/bash or #!/usr/bin/env bash shebang
• Use set -eoux pipefail for strict error handling
• Quote variables: "${VARIABLE}"
• Use meaningful variable names in UPPER_CASE
• Add comments for complex logic
• Follow existing patterns in iso_files/configure_iso_anaconda-webui.sh

Example:

#!/usr/bin/bash
set -eoux pipefail

readonly IMAGE_NAME="aurora"
readonly IMAGE_VERSION="stable"

if [[ -n "${IMAGE_NAME}" ]]; then
    echo "Building ISO for ${IMAGE_NAME}"
fi

YAML Files

• Use 2 spaces for indentation
• Quote strings when necessary
• Use --- document separator
• Keep workflows readable with descriptive names

Markdown

• Use descriptive headings
• Include code blocks with language specification
• Keep lines under 120 characters when possible
• Use relative links for internal documentation

Common Tasks

Adding New ISO Configuration

1. Edit iso_files/configure_iso_anaconda-webui.sh
2. Test syntax: bash -n iso_files/configure_iso_anaconda-webui.sh
3. Create PR with changes
4. Wait for ISO build to complete
5. Test the generated ISO

Modifying Flatpak Lists

1. Flatpaks are defined in Brewfiles in the get-aurora-dev/common repository
2. Edit *system-flatpaks.Brewfile in the common repository
3. Flatpaks are dynamically extracted during ISO build
4. Format: flatpak "app.id.here"

Updating Workflows

1. Edit workflow file in .github/workflows/
2. Validate YAML syntax: pre-commit run check-yaml
3. Create PR and monitor workflow execution
4. Ensure all checks pass

Resources

Documentation

• Aurora Documentation
• Universal Blue Docs
• Titanoboa - ISO builder

Community

• Discourse Forums
• GitHub Discussions
• Discord

Tools

• Pre-commit
• Conventional Commits

Getting Help

If you need help:

1. Check the documentation
2. Search existing issues
3. Ask in Discourse forums
4. Join our Discord

Recognition

Contributors are recognized in several ways:

• Listed in GitHub contributors
• Mentioned in release notes for significant contributions
• Acknowledged in project documentation

Thank you for contributing to Aurora ISO Builder! 🚀