CONTRIBUTING.md

Contributing to GZ302-Linux-Setup

Thank you for your interest in contributing to the GZ302 Linux Setup project! This guide will help you contribute effectively.

🎯 Project Goals

Repository Philosophy (v3.0.0+): The GZ302 Toolkit has evolved from a "hardware enablement" tool into a "performance optimization and convenience toolkit" for modern Linux kernels.

• Hardware-specific: Focused on ASUS ROG Flow Z13 (GZ302EA-XS99) with AMD Ryzen AI MAX+ 395
• Kernel-aware: Automatically adapts to kernel versions (6.14-6.18+), applying only necessary fixes
• Optimization focus: Prioritizes performance tuning over hardware workarounds (for kernel 6.17+)
• Equal distribution support: Arch, Debian/Ubuntu, Fedora, and OpenSUSE receive identical treatment
• Modular design: Core optimizations separated from optional software modules
• Quality focus: Clean, maintainable bash scripts with proper error handling
• Obsolescence handling: Actively removes outdated workarounds that harm performance on modern kernels

🛠️ Development Setup

Prerequisites

• A Linux system (preferably with one of the supported distributions)
• bash 4.0 or higher
• shellcheck for linting (recommended)
• git for version control

Installing ShellCheck

# Arch-based
sudo pacman -S shellcheck

# Debian/Ubuntu-based
sudo apt install shellcheck

# Fedora-based
sudo dnf install ShellCheck

# OpenSUSE
sudo zypper install ShellCheck

📝 Code Style Guidelines

AI/LLM & Copilot Rules

MANDATORY for all AI interactions. If you are using an AI assistant to generate or modify code, you MUST ensure it follows the strict mandates in .github/copilot-instructions.md. This includes rules on library-first architecture, versioning, and idempotency.

Bash Script Standards

...

1. Always use set -euo pipefail at the start of scripts
2. Quote all variables to prevent word splitting: "$variable"
3. Quote command substitutions: "$(command)"
4. Use -r flag with read: read -r -p "prompt: " variable
5. Separate variable declarations:

   # Good
   local var
   var=$(command)
   
   # Avoid
   local var=$(command)  # Can mask return values

6. Kernel-aware logic: When adding hardware fixes, check if they're needed for all kernels:

   # Good - kernel-aware
   if [[ $kernel_version_num -lt 617 ]]; then
       apply_workaround
   else
       info "Native support available, skipping workaround"
   fi
   
   # Avoid - applying fixes unconditionally
   apply_workaround  # May harm performance on newer kernels

Function Conventions

• Use descriptive function names with underscores: install_arch_packages
• Document complex functions with comments
• Return 0 for success, non-zero for errors
• Use local for function-scoped variables

Output Messages

Use the helper functions consistently:

info "Informational message"
success "Success message"
warning "Warning message"
error "Error message (exits script)"

🧪 Testing Your Changes

1. Syntax Validation

Required before committing:

# Test individual script
bash -n gz302-setup.sh

# Test all scripts
for script in gz302-setup.sh gz302-lib/*.sh; do
    bash -n "$script" && echo "✓ $script" || echo "✗ $script FAILED"
done

2. ShellCheck Linting

Required before committing:

# Lint individual script
shellcheck gz302-setup.sh

# Lint all scripts
for script in gz302-setup.sh gz302-lib/*.sh; do
    echo "=== $script ==="
    shellcheck "$script"
done

All scripts must pass with zero warnings.

3. Distribution Testing

Strongly recommended: Test your changes on all supported distributions:

• Arch Linux (or EndeavourOS, Manjaro)
• Ubuntu (or Pop!_OS, Linux Mint)
• Fedora (or Nobara)
• OpenSUSE Tumbleweed or Leap

You can use virtual machines or containers for testing.

🔀 Pull Request Process

1. Fork the repository and create a feature branch
2. Make your changes following the code style guidelines
3. Test thoroughly:
   • Run syntax validation: bash -n script.sh
   • Run shellcheck: shellcheck script.sh
   • Test on target hardware or VM if possible
4. Commit with clear messages:

   Add support for XYZ feature
   
   - Specific change 1
   - Specific change 2
   - Tested on: Arch Linux, Ubuntu 24.04
   

5. Ensure equal distribution support: If you add a feature, implement it for all 4 distributions
6. Submit pull request with:
   • Clear description of changes
   • Testing details (which distributions you tested)
   • Any known limitations or issues

📦 Module Development

When creating or modifying modules (gz302-*.sh):

1. Follow the modular pattern: Each module should be self-contained
2. Include standard helpers: Copy color codes and helper functions
3. Support all distributions: Implement for Arch, Debian, Fedora, OpenSUSE
4. Add proper error handling: Use set -euo pipefail
5. Document usage: Add comments explaining what the module does
6. Consider kernel requirements: Document minimum kernel version if applicable
7. Distinguish fixes from optimizations: Clearly label hardware workarounds vs performance tuning

Module Template

#!/bin/bash

# ==============================================================================
# GZ302 [Module Name] Module
#
# Description of what this module does
# ==============================================================================

set -euo pipefail

# Color codes
C_BLUE='\033[0;34m'
C_GREEN='\033[0;32m'
C_YELLOW='\033[1;33m'
C_RED='\033[0;31m'
C_NC='\033[0m'

# Helper functions
info() { echo -e "${C_BLUE}[INFO]${C_NC} $1"; }
success() { echo -e "${C_GREEN}[SUCCESS]${C_NC} $1"; }
warning() { echo -e "${C_YELLOW}[WARNING]${C_NC} $1"; }
error() { echo -e "${C_RED}[ERROR]${C_NC} $1"; exit 1; }

# Main installation function
install_module() {
    local distro="$1"
   
    case "$distro" in
        "arch") install_arch ;;
        "debian") install_debian ;;
        "fedora") install_fedora ;;
        "opensuse") install_opensuse ;;
        *) error "Unsupported distribution: $distro" ;;
    esac
}

# Distribution-specific functions
install_arch() {
    info "Installing for Arch-based system..."
    # Implementation
}

install_debian() {
    info "Installing for Debian-based system..."
    # Implementation
}

install_fedora() {
    info "Installing for Fedora-based system..."
    # Implementation
}

install_opensuse() {
    info "Installing for OpenSUSE..."
    # Implementation
}

# Entry point
if [[ $# -ne 1 ]]; then
    error "Usage: $0 <distro>"
fi

install_module "$1"

🐛 Bug Reports

When reporting bugs, please include:

1. Distribution and version: cat /etc/os-release
2. Hardware info: lscpu, lspci output
3. Error messages: Complete error output
4. Steps to reproduce: Exact commands you ran
5. Expected vs actual behavior: What should happen vs what happened

💡 Feature Requests

For new features:

1. Check existing issues to avoid duplicates
2. Describe the use case: Why is this feature needed?
3. Hardware relevance: Is it specific to GZ302 hardware?
4. Distribution support: Can it work on all 4 distributions?
5. Kernel compatibility: Does it require specific kernel versions?
6. Type of feature: Is it a hardware fix, optimization, or convenience tool?

Feature Categories

Hardware Fixes (workarounds for broken hardware):

• Only add if hardware genuinely doesn't work without it
• Document kernel version where native support arrives
• Include obsolescence plan

Optimizations (performance tuning):

• Always safe to apply, even if benefits are small
• Examples: GTT size for AI workloads, power profiles

Convenience Tools (quality of life):

• Wrappers around existing tools (asusctl, etc.)
• GUI utilities, system tray integrations
• The core of the "toolkit" philosophy

� Versioning (MANDATORY)

ALL changes require a version bump following semantic versioning (MAJOR.MINOR.PATCH):

When to Bump Versions

• PATCH (X.X.+1): Bug fixes, documentation updates, minor improvements, dependency updates, typo fixes
• MINOR (X.+1.0): New features, new hardware support, module additions, non-breaking enhancements
• MAJOR (+1.0.0): Breaking changes, major architecture changes, incompatible API changes

Version Update Workflow

REQUIRED for EVERY change - follow this exact order:

1. Update root VERSION file FIRST

   echo "5.1.2" > VERSION

2. Sync to ALL locations (use search/replace to ensure consistency):

   • gz302-setup.sh — Header: # Version: 5.1.2 + help text version display
   • gz302-lib/*.sh — All library files: # Version: 5.1.2
   • modules/*.sh — All modules: # Version: 5.1.2
   • command-center/VERSION — 5.1.2
   • command-center/src/command_center.py — Update About dialog version string
   • pkg/arch/PKGBUILD — pkgver=5.1.2
   • README.md — Update any version badges or references
   • docs/CHANGELOG.md — Add new version entry with changes

3. Verify version sync:

   # Check all version headers match
   grep -rn "Version:" gz302-setup.sh gz302-lib/ modules/ | grep -v "Kernel Version"
   cat VERSION command-center/VERSION
   grep "pkgver=" pkg/arch/PKGBUILD

4. Commit with version in message:

   git add -A
   git commit -m "Bump version to 5.1.2: Fix tray icon SVG rendering"

Examples

• Fixed a bug? → PATCH: 5.1.1 → 5.1.2
• Added a new module? → MINOR: 5.1.2 → 5.2.0
• Changed installer architecture? → MAJOR: 5.2.0 → 6.0.0
• Updated documentation only? → PATCH: 5.1.2 → 6.0.0
• Fixed typo in comments? → PATCH: 6.0.0 → 6.0.0

NO exceptions - every merged change must increment the version number.

📚 Documentation

When updating documentation:

1. Keep README.md user-focused: Installation and usage instructions
2. Update version numbers per the Versioning section above
3. Use clear examples: Show actual commands users would run
4. Maintain consistency: Follow existing formatting and style

✅ Checklist Before Submitting

• Version bumped in root VERSION file and synced to all locations
• CHANGELOG.md updated with version entry and changes
• Code passes bash -n syntax check
• Code passes shellcheck with zero warnings
• Changes tested on at least one supported distribution
• All 4 distributions have equivalent implementation
• Documentation updated if needed
• Commit messages are clear and descriptive
• Commit includes version number: "Bump version to X.Y.Z: Description"
• No sensitive data (credentials, personal info) in commits

🤝 Code Review

All contributions go through code review:

• Maintainers will review for code quality, security, and compatibility
• Feedback will be provided constructively
• You may be asked to make changes before merging
• Be patient - reviews may take a few days

📞 Getting Help

• Questions: Open a GitHub issue with the "question" label
• Discussion: Use GitHub Discussions for general topics
• Security issues: Report privately to the maintainer

📜 License

By contributing, you agree that your contributions will be provided as-is for the GZ302 community, matching the project's license.

---

Thank you for helping make GZ302 Linux Setup better! 🎉