Be released on PyPI. Users should be able to install libraries with pip without cloning Git repositories or running shell scripts.
Include a full package description on PyPI. Generally, this can reuse the README so that users can quickly understand a package when they find it on PyPI.
Publish packages automatically to PyPI using Trusted Publishing. Use a GitHub Actions workflow triggered by a published GitHub Release, a protected publishing environment, narrowly scoped OpenID Connect permissions, and artifacts that were built and tested separately. This reduces manual error and avoids long-lived PyPI credentials.
Support the latest stable Gymnasium and/or PettingZoo API. Supporting other APIs as well is fine. Using a current standard API makes environments easier to exchange and application code more modular.
Declare and test a supported Python version range. Projects should support all stable, non-EOL CPython versions when their dependencies permit it, and should document any exceptions or platform-specific constraints.
Display the supported Python versions as a badge in the README. Users should not have to read packaging metadata to learn whether a project supports their interpreter. Use the same shields.io Python-version badge as the other projects and point it at the package on PyPI so that it stays current as support changes.
Apply consistent linting and formatting. It makes easier to work with the project, we recommend making Python code to comply with Black, Flake8, and isort standards.
Add type hints where reasonable. Prioritize public-facing portions of the repository. Type hints can make code easier to understand and can help prevent or catch obscure bugs.
Include docstrings for all substantial functions. We recommend using the Google docstring convention and enforcing it with pydocstyle so that documentation is consistently formatted and easy to understand.
Run continuous integration tests. Test API compliance and determinism, and run type checking with Pyright. Tests must pass for all supported operating-system, architecture, and Python combinations.
Test built distributions before release. In continuous integration, build the source distribution and wheel, install them in clean environments, and run import and API-compliance tests. This catches missing package data, incorrect metadata, and build-isolation problems that tests against the source checkout may miss.
Include pre-commit hooks. Running linting checks through pre-commit helps contributors follow the project’s style automatically. Run the same checks in continuous integration so they cannot be skipped inadvertently.
Automatically check the documentation website and README for broken links. Links rot as pages are renamed and external projects move, and dead links are a common source of frustration. Run a link checker over the built documentation and README from a scheduled GitHub Actions workflow so that maintainers discover breakages before users do.
Include a thorough documentation website when the project’s user-facing scope warrants one. Follow the format of other mature projects so that experienced researchers and newcomers can understand the library and find reference material without reading its source.
Include an AGENTS.md file when the project may benefit from AI-assisted contributions. Document project-specific setup, testing, style, and contribution guidance so that coding agents can work safely and consistently without duplicating general contributor documentation.
Support x86_64 and Arm on Linux, and Apple silicon on macOS. The vast majority of software in this field runs on Linux servers, while many researchers develop on macOS. Students also often use Windows, so support for Windows x86_64 and Arm is encouraged when the project can support and test them reliably.
Provide wheels for supported platforms. Projects with native extensions should publish wheels for every supported operating-system, architecture, and Python combination. Pure-Python projects should publish a universal wheel.
Make native builds reproducible. Projects that distribute native binaries or compile code during installation should document and test their build inputs to reduce irreproducible artifacts.
Document and test determinism guarantees. Given the same seed, environment configuration, supported platform, and dependency versions, results should be reproducible within documented numerical tolerances. Any known nondeterministic backends or operations must be identified.
Include explicit versioning in environment and wrapper names. Use identifiers such as Pong-v5 when configuration or behavior changes can affect scientific results, so that researchers can identify comparable environments.
Make environments reconstructible for supported workflows. Preserve the constructor arguments and state needed for experiment reproduction or process-based vectorization, using EzPickle or another documented mechanism where appropriate. Pickle data must be treated as trusted and compatibility boundaries must be documented.
Include polished rendering where visual rendering is meaningful. Rendering should be inviting and informative, especially for newcomers to reinforcement learning. Headless or abstract environments may omit rendering when that limitation is documented.
Include descriptive warnings and error messages. Raise explicit exception types for invalid input and runtime conditions, and use warnings for recoverable or deprecated behavior. Reserve assert statements for internal invariants because optimized Python can disable them.
Use an MIT-style open source license. Apache 2.0 and similarly permissive licenses are also acceptable. An explicit open source license is necessary to distribute free and open source software, and permissive licenses make broad reuse possible.
Generate documentation website information from environments directly. Avoid manually transcribing information that can be extracted from the source, which reduces errors and prevents documentation from becoming stale.
Have a logo in the same style as the other projects. A polished logo makes a project more memorable and helps it fit naturally alongside the other Farama projects.
Have a documentation website at [project].farama.org. Keeping project websites under one domain makes them consistent for users and easier for Farama to manage.
Include the standard Farama code of conduct. All members of our community should be respected. A published code of conduct is also required for some open source donations.
Include a header image at the top of the README in the same style as the other projects. The README header is often a visitor’s first impression. A consistent image makes the project recognizable and clearly associates it with Farama.
Set the GitHub social media preview image on the repository. This image appears when a repository link is shared on social media or in chat applications. Upload the project’s header image under Settings > General > Social preview so that shared links are recognizable instead of using a generic placeholder.
Use a consistent project tagline everywhere the project is described. Keep the tagline consistent across the Farama projects page, GitHub repository About section, project Discord channel description, and documentation website subheader so that users receive the same description at every entry point.
Do it right the first time and eliminate technical debt. Build flexible APIs that can be maintained for many years. Bringing an outside project into alignment with these standards may require carefully managed breaking changes.
Make APIs user-friendly and resistant to incorrect usage. New users should be able to use APIs correctly without needing to inspect the source code.
Use deprecation warnings whenever possible. Give users time to adapt before a breaking change. When advance deprecation is impossible, provide detailed errors and migration instructions.
Include only environments that are scientifically important or commonly used. Prefer quality over quantity. Remove environments with little scientific value, or limit them to tutorials. Identify toy environments clearly and include them only when they are widely used.
Make projects polished and professional. Provide a comprehensive README and documentation website with straightforward wording, intuitive explanations, examples, and images.
Keep rendering high-quality and consistent between environments. We generally use Pygame for 2D Python graphics and create pixel art when native rendering does not exist.
Limit each project to a single purpose. Where practical, separate standard APIs, utilities, environments, and datasets into focused repositories to make maintenance and usage simpler.
Limit external dependencies to well-maintained projects. An abandoned dependency can prevent long-term benchmark maintenance. For example, replace unmaintained PyBullet or MuJoCo-py integrations with maintained alternatives where possible.
Use semantic versioning. Limit maintenance releases to 0.0.x version bumps and use 0.x.0 for standard pre-1.0 releases. Reserve 1.0.0 for initial maturity and later x.0.0 releases for significant API changes or major functionality.
Limit commits and PRs to a single purpose. Focused changes make reviews easier and reduce the chance of errors slipping into the codebase.
Use main as the default branch. Rename projects that still use master when they join Farama. Consistent branch naming means contributors working across projects do not have to track different conventions.
Block direct commits to the default branch in the repository settings. Develop on feature branches and merge them through PRs so that changes are reviewed. Add a GitHub ruleset targeting the default branch that requires a pull request before merging and blocks force pushes.
Communicate clearly with the community about upcoming changes. Share future development plans through release notes, appropriate announcements, and public roadmaps. Provide specific migration instructions for breaking changes.
Verify and sign commits with GPG or SSH keys. Signed commits help recipients verify that a commit was produced by someone who controls a recognized signing key.
List Jordan Terry, Mark Towers, and Marek Wydmuch as owners on PyPI. Multiple owners reduce the risk of losing control of a package if a primary maintainer becomes unexpectedly unavailable.
Require maintainers with GitHub or PyPI permissions to use TOTP-based 2FA or better. Strong authentication, secure passwords, and secure email addresses reduce the likelihood of supply-chain attacks against Farama projects.
Use Farama Notifications. Notifications let us warn users of older releases about important issues discovered after publication.
Include Google Analytics on all documentation websites. Analytics help us understand project popularity and how users navigate the documentation.
Include a Sponsor this project button on the GitHub repository. Add .github/FUNDING.yml with github: Farama-Foundation.