CONTRIBUTING.md

Contributing Guide

Thank you for contributing to VeriRL! This guide explains the development workflow.

Workflow Overview

1. Create feature branch from main
2. Make changes
3. Create changelog fragment (.changelog.d/<ID>.{feature,bugfix,doc,misc}.md)
4. Push to your fork
5. Create pull request to main
6. CI/CD runs (validate, docker build) on PR
7. Review & merge to main
8. CI/CD auto-deploys to HF Spaces
9. Create release via GitHub Actions (bumps version, publishes Docker image)

Branch Protection Rules

The main branch is protected:

• ✓ No direct pushes — all changes via pull requests
• ✓ Requires status checks — openenv validate + docker build must pass
• ✓ Requires reviews — at least 1 approval recommended
• ✓ Requires updated branch — must be up-to-date with main

Step-by-Step Guide

1. Set Up Local Environment

# Clone the repo
git clone https://github.com/SupreethRao99/veriRL.git
cd veriRL

# Create feature branch
git checkout -b feature/your-feature-name

# Install dependencies
uv sync

# Verify environment works
openenv validate

2. Make Changes

# Edit files, add features, fix bugs
vim server/verirl_env_environment.py
vim tests/test_environment.py

# Test locally
pytest
openenv validate
docker build -t verirl:test -f server/Dockerfile .

3. Create Changelog Fragment

For EVERY change, create a fragment:

# Feature
echo "Added new task: XYZ accelerator" > .changelog.d/pr-123.feature.md

# Bug fix
echo "Fixed STDOUT format parsing" > .changelog.d/pr-124.bugfix.md

# Documentation
echo "Updated README with new examples" > .changelog.d/pr-125.doc.md

# Internal (not shown in changelog)
echo "Refactored evaluator for clarity" > .changelog.d/pr-126.misc.md

Fragment format:

• File: .changelog.d/<ID>.<TYPE>.md
• ID: PR number, commit hash, or unique identifier
• TYPE: feature, bugfix, doc, misc
• Content: One-line description

4. Commit & Push

# Stage changes
git add server/ tests/ .changelog.d/

# Commit with clear message
git commit -m "Add new task and update documentation

- Implement XYZ accelerator task
- Add 25 test cases
- Update README with task description
- Create changelog fragment"

# Push to your fork
git push origin feature/your-feature-name

5. Create Pull Request

1. Go to https://github.com/SupreethRao99/veriRL/pulls
2. Click "New pull request"
3. Select: main ← feature/your-feature-name
4. Fill in description:

   ## Summary
   Add XYZ accelerator task to environment
   
   ## Changes
   - New task with 25 assertions
   - Updated scoring weights
   - Added reference implementation
   
   ## Testing
   - [x] openenv validate passes
   - [x] Docker builds successfully
   - [x] All tests pass locally
   

5. Submit PR

6. CI/CD Validation (Automatic)

When you create the PR, GitHub Actions automatically:

• ✓ Validates openenv spec
• ✓ Builds Docker image
• ✓ Runs tests

If checks fail:

1. Review error logs in Actions tab
2. Fix issues locally
3. Commit and push again
4. Checks re-run automatically

7. Review & Merge

• Code review (recommended)
• Request changes if needed
• Merge to main when ready

# GitHub UI: Click "Merge pull request"
# Or via CLI:
gh pr merge <PR_NUMBER>

8. Auto-Deploy (On Merge)

When you merge to main, GitHub Actions automatically:

1. Validates environment
2. Builds Docker image
3. Pushes image to ghcr.io as main tag
4. Deploys to HF Spaces

Done! Your changes are live.

9. Create Release (Optional)

When ready to cut a release:

1. Go to https://github.com/SupreethRao99/veriRL/actions
2. Click "Release" workflow
3. Click "Run workflow"
4. Enter version (e.g., 0.3.0)
5. Workflow:
   • Generates CHANGELOG.md from fragments
   • Updates version in pyproject.toml
   • Creates git tag v0.3.0
   • Builds & pushes Docker image to ghcr.io/SupreethRao99/veriRL:v0.3.0
   • Creates GitHub Release

Done! Release is published with versioned Docker image.

Naming Conventions

Branch Names

feature/<name>      New feature or task
bugfix/<name>       Bug fix
docs/<name>         Documentation update
refactor/<name>     Code refactoring

Examples:

feature/axi-fifo-task
bugfix/stdout-format
docs/deployment-guide
refactor/evaluator

Commit Messages

<type>: <subject>

<body>

<footer>

Types: feat, fix, docs, refactor, test, chore

Example:

feat: Add AXI-Stream FIFO task

- Implement 4-entry FIFO with backpressure
- Add 34 test assertions
- Update README with task description

Fixes #123

Testing Locally

Before pushing:

# Run tests
pytest

# Check code style (if configured)
# pycodestyle, black, ruff, etc.

# Validate environment
openenv validate

# Build Docker image
docker build -t verirl:test -f server/Dockerfile .

# Test inference (if server is running)
export ENV_BASE_URL=http://localhost:8000
python inference.py

Common Issues

"Validation failed on PR"

1. Check error message in Actions tab
2. Run locally: openenv validate
3. Fix issue
4. Push again

"Docker build failed"

1. Check Dockerfile
2. Build locally: docker build -f server/Dockerfile .
3. Fix and commit
4. Re-run workflow

"Can't push to main"

• Branch protection is enabled
• Create PR from feature branch instead
• Merge via pull request

"Forgot changelog fragment"

1. Create fragment: .changelog.d/<ID>.<TYPE>.md
2. Commit: git add .changelog.d/ && git commit -m "Add changelog fragment"
3. Push
4. Checks re-run

Version Numbers

Uses Semantic Versioning: MAJOR.MINOR.PATCH

• 0.1.0 → 0.2.0 = new feature/task (minor bump)
• 0.2.0 → 0.2.1 = bug fix (patch bump)
• 0.2.1 → 1.0.0 = breaking change (major bump)

Docker Images

Every merge to main publishes an image:

ghcr.io/SupreethRao99/veriRL:main

Every release publishes versioned images:

ghcr.io/SupreethRao99/veriRL:v0.2.0
ghcr.io/SupreethRao99/veriRL:latest

Pull and run:

docker pull ghcr.io/SupreethRao99/veriRL:v0.2.0
docker run -p 8000:8000 ghcr.io/SupreethRao99/veriRL:v0.2.0

Questions?

• Check existing issues: https://github.com/SupreethRao99/veriRL/issues
• Review past PRs: https://github.com/SupreethRao99/veriRL/pulls
• Check RELEASES.md for release management details

---

Thank you for contributing! 🚀