Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (102 loc) · 5.47 KB

CONTRIBUTING.md

File metadata and controls

141 lines (102 loc) · 5.47 KB
Raw

Contributing to ralph

Thanks for your interest in contributing! ralph is a dependency-free Bash / PowerShell loop wrapper that runs an AI coding CLI in a fresh session each iteration. Contributions of all kinds are welcome: bug reports, documentation, new agent integrations, skill improvements, and code.

By participating, you agree to abide by our Code of Conduct.

Ways to contribute

Pull Request Process

For External Contributors

  1. Fork the repository to your GitHub account.
  2. Create a branch from main with a descriptive name: 
    git checkout -b feature/add-new-agent
  3. Make your changes following the Code Style guidelines.
  4. Keep Bash and PowerShell in sync — see Bash ↔ PowerShell parity.
  5. Add or update tests for any new behaviour.
  6. Update documentation (README.md) if your change affects configuration or usage.
  7. Commit with clear messages following Conventional Commits: 
    feat: add support for a new agent CLI
fix: keep previous config when .env has an invalid value
docs: clarify the RALPH_MEMORY_MAX behaviour
  8. Push your branch and open a Pull Request against main.
  9. Sign the CLA when prompted by the CLA Assistant bot.
  10. Wait for review — a maintainer will review your PR within 2 weeks (SLA).

For Internal Contributors (Santander)

  1. Create a branch from main (no fork needed if you are a member of the org).
  2. Follow steps 3-8 above.
  3. Request review from the maintainer team in CODEOWNERS.

PR Requirements

All pull requests must pass the following automated checks before merge:

  • CI lint and tests (ci) — ShellCheck, PSScriptAnalyzer, and the bats test suite
  • License check (license-check) — SPDX header verification
  • Pattern check (pattern-check) — No internal URLs, IPs, or corporate email addresses
  • Supply-chain (scorecard) — OpenSSF Scorecard analysis
  • CLA signed (for external contributors)

Additionally:

  • At least 1 maintainer approval is required.
  • All review conversations must be resolved.
  • The branch must be up to date with main.

Bash ↔ PowerShell parity

The loop ships as two equivalent implementations:

  • ralph-loop.sh — Bash version (canonical reference).
  • ralph-loop.ps1 — PowerShell version (pwsh 6+), with the same capabilities.

Mandatory rule: any behavioural change (a new RALPH_* option, a change to the tool-rotation cycle, to token-exhaustion detection, to the log format, to stop.md handling, to default flags, etc.) must be applied to BOTH files in the same commit, so their observable behaviour stays identical. Do not leave one lagging behind the other.

Known and accepted difference: the RAM limit (RALPH_MEMORY_MAX) is enforced only on Linux via systemd-run --user --scope. On other platforms both versions print a one-time warning and run the agent without a limit.

Code Style

Shell (Bash / PowerShell)

  • Bash targets bash with set -u; pass ShellCheck with no warnings.
  • PowerShell targets pwsh 6+ with Set-StrictMode -Version Latest; pass PSScriptAnalyzer.
  • Prefer small, single-purpose functions; quote all expansions; avoid eval.

File Headers

Every script must include the copyright header (after the shebang line):

# Copyright (c) 2026 César Gallego Rodríguez
# SPDX-License-Identifier: Apache-2.0

Commit Messages

Follow Conventional Commits:

Prefix Use
feat: New feature
fix: Bug fix
docs: Documentation only
test: Adding or updating tests
refactor: Code refactoring (no feature/fix)
ci: CI/CD changes
chore: Maintenance tasks

Testing

  • Tests live in tests/ and use bats (Bash Automated Testing System).
  • Run the suite locally before submitting a PR: 
    bats tests/
  • New behaviour in ralph-loop.sh should come with a bats test that does not require any AI CLI to be installed (use the argument-validation and stop.md paths, which exit before launching an agent).

Contributor License Agreement (CLA)

By submitting a pull request, you agree to the terms of our Contributor License Agreement. The CLA Assistant bot will automatically check your PR and ask you to sign the CLA if you have not already done so.

The CLA ensures that contributions can be distributed under the project's Apache 2.0 license.

Release Process

This project follows Semantic Versioning (SemVer):

  • MAJOR — Incompatible changes to configuration keys or CLI contract
  • MINOR — New features (backward-compatible)
  • PATCH — Bug fixes (backward-compatible)

Releases are managed by maintainers. If you believe a release is warranted, open an issue to discuss.

Thank you for contributing to ralph!