Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
81 lines (56 loc) · 3.91 KB

CONTRIBUTING.md

File metadata and controls

81 lines (56 loc) · 3.91 KB
Raw

Contributing to OADP Rebase

Prerequisites

Install these tools before working on this repository:

  • yq (Mike Farah's, not Python yq) — used by all shell tooling to read repos.yaml
  • Go 1.25+ — for building and testing the tools in tools/
  • ShellCheck — for linting shell scripts (make shellcheck)
  • gh — GitHub CLI, used by CI scripts and the rebase-status tool
  • jq — used by several shell scripts for JSON processing

For running actual rebases (not required for config/hook changes):

  • podman or docker — rebasebot runs in a container
  • rebasebot — the rebase engine itself; see the rebasebot repo
  • A ~/.rebasebot/secrets/ directory with GitHub tokens

Validation

Always run make test before committing. It checks:

  • repos.yaml is valid and config prefixes have matching files
  • Generated files match the SSOT (make generate + git diff)
  • All shell scripts parse without errors (bash -n)
  • Every config loads successfully for its branch
  • The resolve-config.sh script maps targets to the correct config names
  • Every hook script referenced in a config exists on disk
  • Go unit tests pass for all tools
  • The 90-test auto-rebase decision/triage test suite passes

Additionally, make shellcheck lints all scripts (run separately or in CI).

Common Workflows

Update an upstream tag

When a new upstream release comes out (e.g., Velero v1.18.3):

  1. Edit versions/oadp-1.X.env — update the relevant *_TAG and *_SHA variables
  2. Run make generate — regenerates hook scripts and docs/version-matrix.md
  3. Run make test — validates everything is consistent
  4. Commit both the versions file and all generated files

Add a new repository

  1. Add the repo entry to repos.yaml with org, repo name, wave, config_prefix, and optionally min_branch, max_branch, dev_branch, main_only, or images
  2. Create config files in rebase-configs/ for each branch the repo supports, named <config_prefix>_<branch>.env.sh
  3. Create or adapt any hook scripts the repo needs in rebasebot-hook-scripts/ and reference them from the config files
  4. Run make generate — updates docs/version-matrix.md and generates version-specific hooks
  5. Run make test

Add a new OADP version (e.g., oadp-1.7)

  1. Create versions/oadp-1.7.env with all upstream tag variables
  2. Update min_branch/max_branch in repos.yaml if any repos are being added or removed for this version
  3. Create config files in rebase-configs/ for each repo that has the new branch
  4. Copy and adapt version-specific hook scripts in rebasebot-hook-scripts/ — most hooks differ only by the branch name on one line, so copy from the previous version and update the branch
  5. Run make generate — creates generated hooks (go-replace_velero_*, verify-tag-sha_*) and updates the version matrix
  6. Run make test

Add or modify a hook script

Most hook scripts are hand-maintained files in rebasebot-hook-scripts/. A few are generated from the SSOT — see the "do not edit manually" header in go-replace_velero_*.sh and verify-tag-sha_*.sh.

For hand-maintained hooks:

  1. Create or edit the script directly in rebasebot-hook-scripts/
  2. Reference it from the relevant config files in rebase-configs/
  3. Run make test — verify-hooks confirms every referenced file exists

For generated hooks (go-replace_velero_*, verify-tag-sha_*):

  1. Modify the generator script in tools/generate-*.sh
  2. Run make generate
  3. Review the changes across all generated files
  4. Run make test

Project Structure

See CLAUDE.md for a concise overview. For deeper architecture details including data flow, the wave system, and hook execution, see AGENTS.md.