# How to Submit a Pull Request for OpenEnv: Complete Contributor Guide > Learn how to submit a pull request for OpenEnv. Fork the repo, create branches, implement changes, and run quality checks before opening your PR to the main branch. - Repository: [Hugging Face/OpenEnv](https://github.com/huggingface/OpenEnv) - Tags: how-to-guide - Published: 2026-06-16 --- **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`](https://github.com/huggingface/OpenEnv/blob/main/CONTRIBUTING.md) for the full checklist and environment setup details. ```bash # Clone your fork git clone https://github.com//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//` containing a `Dockerfile`, [`openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/openenv.yaml), and server code in `envs//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: ```bash # 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`](https://github.com/huggingface/OpenEnv/blob/main/CLAUDE.md), you must follow the `docs/` generation rules when modifying public interfaces. Review [`.claude/docs/INVARIANTS.md`](https://github.com/huggingface/OpenEnv/blob/main/.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: ```bash 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`](https://github.com/huggingface/OpenEnv/blob/main/.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`](https://github.com/huggingface/OpenEnv/blob/main/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`](https://github.com/huggingface/OpenEnv/blob/main/.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//` with three required components: a `Dockerfile`, an [`openenv.yaml`](https://github.com/huggingface/OpenEnv/blob/main/openenv.yaml) configuration file, and server code located in `envs//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`](https://github.com/huggingface/OpenEnv/blob/main/.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.