How to Submit a Pull Request for OpenEnv: Complete Contributor Guide

To submit a pull request for OpenEnv, fork the repository, create a feature branch, implement your changes, run the local quality checks with pytest and ruff, and open a PR against the upstream main branch.

OpenEnv, maintained by Hugging Face, follows an agent-first contribution workflow that combines standard GitHub practices with Claude Code automation. Whether you are fixing a bug, adding a new environment, or updating core logic, understanding how to submit a pull request for OpenEnv ensures your contribution passes automated checks and aligns with project invariants.

Prerequisites and Repository Setup

Before writing code, fork the repository on GitHub and clone your local copy. Consult CONTRIBUTING.md for the full checklist and environment setup details.

# Clone your fork

git clone https://github.com/<your-username>/OpenEnv.git
cd OpenEnv

# Create a feature branch off main

git checkout -b feature/your-change-name

Step-by-Step Pull Request Workflow

1. Implement Your Changes

Modify the relevant code paths based on your contribution type:

• Core library changes: Edit files under src/openenv/ (client/server logic, data models like Action, Observation, or State)
• New environments: Create a directory under envs/<env-name>/ containing a Dockerfile, openenv.yaml, and server code in envs/<env-name>/server/
• Tests: Add corresponding test files under tests/ to cover your modifications

2. Run Quality Checks

OpenEnv enforces strict code quality standards. Run these commands locally before committing to ensure the CI pipeline will pass:

# Run the full test suite with correct Python path

PYTHONPATH=src:envs uv run pytest tests -v

# Check formatting and linting

uv run ruff format src/ tests/ --check

These commands verify that your code is correctly formatted, lint-free, and that all tests pass. The CI configuration in .github/workflows/ will reject PRs that fail these checks.

3. Update Documentation

If you altered any public API or added a new environment, update the relevant documentation. According to CLAUDE.md, you must follow the docs/ generation rules when modifying public interfaces. Review .claude/docs/INVARIANTS.md to ensure your changes do not violate project-wide architectural rules.

4. Submit the Pull Request

Push your branch to your fork and open a PR against the upstream main branch:

git add .
git commit -m "feat: descriptive commit message"
git push origin feature/your-change-name

In the GitHub UI, target the main branch. Include a clear summary of changes and reference any related RFC if applicable.

Understanding the Automated Review Process

OpenEnv uses Claude Code agents for automated review. When you open a PR, the pre-submit-pr skill runs automatically through GitHub Actions. This process includes:

• Linting and testing: Re-running the pytest and ruff checks
• Alignment review: The alignment-reviewer agent checks code correctness and compliance with invariants defined in .claude/docs/INVARIANTS.md

The repository also supports a two-phase TDD workflow when using the /work-on-issue skill. If you are working in this mode, the agent manages the test-driven development cycle, but the standard PR submission steps remain the same.

RFC Process for Substantial Changes

For large-scale changes or new architectural features, OpenEnv requires a Request for Comments (RFC) before submitting the PR:

1. Copy the template: cp rfcs/template.md rfcs/rfc-XXX-my-feature.md
2. Fill in the details following the guidance in rfcs/README.md
3. Submit a separate PR to the rfcs/ directory to get community approval
4. Once approved, proceed with the implementation PR

This process ensures significant changes align with the project's long-term vision.

Summary

• Fork and branch off main before making changes
• Implement changes in src/openenv/ for core logic or envs/ for new environments
• Run quality checks locally using PYTHONPATH=src:envs uv run pytest tests -v and uv run ruff format src/ tests/ --check
• Update documentation and verify compliance with invariants in .claude/docs/INVARIANTS.md
• Open an RFC first for substantial changes under rfcs/
• Submit the PR to the upstream main branch and await automated alignment review

Frequently Asked Questions

What quality checks must pass before submitting a pull request for OpenEnv?

You must run PYTHONPATH=src:envs uv run pytest tests -v to verify the test suite passes and uv run ruff format src/ tests/ --check to ensure proper formatting and linting. These checks mirror the CI pipeline in .github/workflows/ and must pass locally before opening the PR.

Where should I place code for a new environment in my OpenEnv pull request?

New environments belong under envs/<env-name>/ with three required components: a Dockerfile, an openenv.yaml configuration file, and server code located in envs/<env-name>/server/. This structure ensures environments are properly isolated as Docker containers.

What is the alignment-reviewer agent in OpenEnv?

The alignment-reviewer is a Claude Code agent that automatically reviews pull requests for code correctness and compliance with project invariants. It runs as part of the pre-submit-pr skill when you push to GitHub, checking against rules defined in .claude/docs/INVARIANTS.md.

When do I need to open an RFC before submitting a pull request?

Open an RFC for substantial changes that affect architecture, public APIs, or add major new features. Create the RFC under rfcs/ using the template, submit it for community approval, and reference it in your PR description. Minor bug fixes and documentation updates do not require an RFC.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}