Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
140 lines (99 loc) · 4.46 KB

CONTRIBUTING.md

File metadata and controls

140 lines (99 loc) · 4.46 KB

Contributing

Development Setup

  1. Clone the repository:
git clone https://github.com/xooooooooox/radp-bash-framework.git
cd radp-bash-framework
  1. Source the framework directly:
source src/main/shell/framework/init.sh

Testing

Tests use bats-core.

# Run all tests
bats src/test/shell/

# Run specific test file
bats src/test/shell/toolkit_core.bats

# Run with verbose output
bats --verbose-run src/test/shell/toolkit_core.bats

See src/test/shell/README.md for writing new tests.

Preflight Architecture

The framework uses a two-stage preflight system to check and install dependencies:

preflight/
├── preflight.sh              # Entry point, orchestrates stages
├── stage1/                   # POSIX shell (bash check only)
│   ├── stage1.sh             # Stage 1 main
│   └── bash.sh               # Bash version check/install
└── stage2/                   # Bash (other dependencies)
    ├── stage2.sh             # Stage 2 main
    ├── lib.sh                # Common utilities
    ├── gnu_getopt.sh         # GNU getopt check/install
    └── yq.sh                 # yq check/install

Why two stages?

  • Stage 1 runs in POSIX shell to bootstrap bash itself (can't use bash features before bash is confirmed)
  • Stage 2 runs in bash after stage 1 completes, allowing cleaner code with local, [[ ]], arrays, etc.

Adding a new dependency:

  1. Create stage2/<name>.sh with __check_<name>() and __install_<name>() functions
  2. Add entry to __REQUIREMENTS array in stage2/stage2.sh

Code Style

See Code Style Guide for naming conventions, formatting rules, and POSIX vs Bash layering.

Release Process

Workflow Chain

flowchart TD
    A["release-prep<br/>(manual trigger)"] --> B["PR merged"]
    B --> C["create-version-tag"]
    C --> D["update-spec-version"]
    C --> E["update-homebrew-tap"]
    C --> F["GitHub Release"]
    D --> G["build-copr-package"]
    D --> H["build-obs-package"]
    G --> I["attach-release-packages"]
    H --> I
    J["cleanup-branches<br/>(weekly/manual)"] -.-> K["Delete stale<br/>workflow/v* branches"]
Loading

1. Prepare Release

Trigger release-prep workflow with bump_type (patch/minor/major/manual):

  • Creates branch workflow/vX.Y.Z
  • Updates gr_fw_version in version.sh
  • Syncs spec versions
  • Generates changelog entry from commits
  • Regenerates shell completion scripts
  • Opens PR for review

2. Review and Merge

Edit changelog in PR, then merge to main.

3. Create Tag

create-version-tag runs automatically on merge:

  • Validates version, changelog, spec versions
  • Creates and pushes git tag

4. Build Packages

Tag triggers:

  • update-homebrew-tap - Updates Homebrew formula
  • update-spec-version - Updates spec Version field
  • build-copr-package - Triggers COPR SCM build
  • build-obs-package - Syncs to OBS and triggers build

5. Attach Assets

attach-release-packages downloads built packages from COPR/OBS and uploads to GitHub Release.

6. Branch Cleanup

cleanup-branches runs weekly (Sunday 00:00 UTC) or manually:

  • Deletes stale workflow/v* branches older than 14 days
  • Supports dry-run mode to preview deletions
  • Configurable days threshold via manual trigger

GitHub Actions Reference

Workflow Trigger Purpose
release-prep.yml Manual on main Create release branch and PR
create-version-tag.yml PR merge or manual Validate and create git tag
update-spec-version.yml After tag creation Update spec Version field
build-copr-package.yml After spec update Trigger COPR build
build-obs-package.yml After spec update Sync to OBS and build
update-homebrew-tap.yml Tag push Update Homebrew formula
attach-release-packages.yml After package builds Upload packages to release
build-portable.yml Tag push or manual Build portable binary executables
cleanup-branches.yml Weekly schedule or manual Delete stale workflow branches