Contributing to DFE Developer Environment

We welcome contributions from the community! This project follows standard Apache project guidelines.

How to Contribute
Code Standards
Pull Request Guidelines
Development Workflow
Testing
Reporting Issues
Code of Conduct

How to Contribute

1. Fork the Repository

# Fork via GitHub UI, then clone your fork
git clone https://github.com/YOUR-USERNAME/dfe-developer
cd dfe-developer
git remote add upstream https://github.com/hyperi-io/dfe-developer

2. Create a Feature Branch

git checkout -b feature/your-feature-name
# Or for bug fixes
git checkout -b fix/issue-description

3. Make Your Changes

Follow the KISS principle (Keep It Simple, Stupid)
Use existing code style and conventions
Run scripts as regular user with per-command sudo
Test on a clean Fedora 42 system if possible
Update documentation as needed

4. Test Your Changes

cd fedora/tests

# Static analysis (required)
./01-shellcheck.sh

# Syntax validation
bats 02-syntax.bats

# Unit tests
bats 03-lib-functions.bats

# Container tests (optional)
bats 04-container.bats

5. Commit Your Changes

Use conventional commit format:

feat: - New features
fix: - Bug fixes
docs: - Documentation changes
chore: - Maintenance tasks
refactor: - Code refactoring
test: - Test additions or fixes

git add .
git commit -m "feat: add support for Ubuntu 22.04"

Important:

Write clear, concise commit messages
No tool attribution in commit messages
Reference issue numbers: fix: resolve #123

6. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a PR via GitHub UI targeting the main branch.

Code Standards

Shell Script Guidelines

Shebang: Always use #!/bin/bash
Error Handling: Scripts must source lib.sh and use centralized error handling
Execution: Run as regular user, use sudo only when needed
Idempotency: Scripts must be safe to run multiple times
Library Functions: Use lib.sh functions for consistency
- print_info() - Informational messages
- print_error() - Error messages
- print_warning() - Warning messages
- print_success() - Success messages

Code Style

# Good - uses lib.sh functions
print_info "Installing package..."
sudo dnf install -y package-name

# Bad - direct echo
echo "Installing package..."

File Operations

# Good - use pushd/popd
pushd /tmp >/dev/null || exit 1
# do work
popd >/dev/null || exit 1

# Bad - use cd
cd /tmp
# do work
cd -

Version Detection

Always detect latest versions dynamically, never hardcode:

# Good - dynamic detection
CONFLUENT_VERSION=$(curl -sL https://packages.confluent.io/rpm/ 2>/dev/null | grep -oE '[0-9]+\.[0-9]+' | sort -V | tail -1)
if [ -z "$CONFLUENT_VERSION" ]; then
    print_warning "Could not detect latest version, using fallback"
    CONFLUENT_VERSION="8.1"
fi

# Bad - hardcoded version
CONFLUENT_VERSION="7.7"

Character Policy

All Output: ASCII only - no emojis or special Unicode characters
Console Output: Plain text with standard symbols only
Log Files: Plain ASCII only
Code Comments: ASCII only
Commit Messages: ASCII only

Script Headers

All scripts must have a standardized header:

#!/bin/bash
# ============================================================================
# script-name - Brief Description
# ============================================================================
# Longer description of what the script does
#
# USAGE:
#   ./script-name.sh [options]
#
# INSTALLS/OPTIMIZES:
#   - Item 1
#   - Item 2
#
# NOTE: Important context or prerequisites
#
# LICENSE:
#   Licensed under the Apache License, Version 2.0
#   See ../LICENSE file for full license text
# ============================================================================

Pull Request Guidelines

Before Submitting

All tests pass (ShellCheck and BATS)
Code follows project style guidelines
Documentation updated (README.md, STATE.md)
CHANGELOG.md updated if applicable
Commit messages follow conventional format
No merge conflicts with main branch

PR Description

Include:

Summary: What does this PR do?
Motivation: Why is this change needed?
Testing: How was it tested?
Screenshots: If UI changes
Breaking Changes: Clearly marked if any

PR Size

Keep PRs focused and reasonably sized
Split large changes into multiple PRs
One feature or fix per PR

Review Process

Maintainers will review within 48 hours
Address review feedback promptly
Keep PR updated with main branch
Be respectful in discussions

Development Workflow

Setting Up Development Environment

# Clone and setup
git clone https://github.com/YOUR-USERNAME/dfe-developer
cd dfe-developer

# Keep your fork synced
git remote add upstream https://github.com/hyperi-io/dfe-developer
git fetch upstream
git rebase upstream/main

Making Changes

Check existing issues before starting work
Create an issue for discussion if needed
Create a feature branch
Make changes incrementally
Test frequently
Commit with clear messages

Working with lib.sh

When adding functions to lib.sh:

Add function in appropriate section
Include error handling
Add BATS unit test in tests/03-lib-functions.bats
Document function in STATE.md

Example:

# In lib.sh
my_new_function() {
    local param="$1"
    if [ -z "$param" ]; then
        print_error "Parameter required"
        return 1
    fi
    # function logic
    return 0
}

# In tests/03-lib-functions.bats
@test "my_new_function works correctly" {
    run my_new_function "test"
    [ "$status" -eq 0 ]
}

Testing

Required Tests

All contributions must pass:

ShellCheck: Static analysis
```
cd fedora/tests
./01-shellcheck.sh
```
Syntax Tests: Bash syntax validation
```
bats 02-syntax.bats
```
Unit Tests: lib.sh function tests
```
bats 03-lib-functions.bats
```

Optional Tests

Container Tests: Integration tests
```
bats 04-container.bats
```

Test Coverage

New functions must have corresponding unit tests
Changes to existing functions require test updates
Integration tests for installer scripts

Manual Testing

Test Systems:

For HyperSec developers, test systems are available. See STATE.md (not public) for access details.

Fedora (clean VM):

# Reset Fedora test VM (fast - uses snapshot)
# Contact maintainers for test system access

# Test playbook:
ansible-playbook -i tests/fedora/inventory.yml playbooks/main.yml

Ubuntu (clean VM):

# Reset Ubuntu test VM (fast - uses snapshot)
# Contact maintainers for test system access

# Test playbook:
ansible-playbook -i tests/ubuntu/inventory.yml playbooks/main.yml

macOS (clean system):

# ⚠️ WARNING: Mac mini provisioning takes 20-30 minutes!
# Only reset when absolutely necessary (major changes, broken state)
# Use sparingly to avoid unnecessary costs and time
# Contact maintainers for test system access

# Reset Mac mini test system (SLOW - full OS install)
cd ansible
ansible-playbook -i tests/mac/inventory_scaleway.yml tests/provision_scaleway_mac.yml

# Test playbook:
ansible-playbook -i tests/mac/inventory_scaleway.yml playbooks/main.yml

Legacy Fedora Shell Scripts:

cd fedora

# Standard installation
./install-dfe-developer.sh

# Core developer tools
./install-dfe-developer-core.sh

# VM optimizations
./install-vm-optimizer.sh

# RDP optimizations
./install-rdp-optimizer.sh

Reporting Issues

Bug Reports

Use GitHub Issues and include:

Fedora Version: Output of cat /etc/fedora-release
Script: Which script(s) failed
Error Output: Full error messages and logs
Steps to Reproduce: Clear reproduction steps
Expected Behavior: What should have happened
Actual Behavior: What actually happened

Feature Requests