open-thought/reasoning-gym
1
0
Fork 0
mirror of https://github.com/open-thought/reasoning-gym.git synced 2026-04-28 17:29:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Improve CONTRIBUTING.md with better formatting, clarity, and organization

Browse source
This commit is contained in:
Andreas Koepf (aider) 2025-02-08 15:49:48 +01:00
parent 247ea4d8eb
commit 78212450c8
1 changed files with 69 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

120
CONTRIBUTING.md
View file

@ -1,62 +1,80 @@
# Contributing to reasoning-gym # Contributing to Reasoning Gym
### Delevloper Setup Thank you for your interest in contributing to Reasoning Gym! This document provides guidelines and instructions for contributing to the project.
1. Clone the project ## Development Setup
``` 1. Clone the repository:
git clone https://github.com/open-thought/reasoning-gym.git ```bash
``` git clone https://github.com/open-thought/reasoning-gym.git
```
2. Create a virtual environment (here we use conda) 2. Create a virtual environment (using conda):
```bash
conda create --name reasoning_gym python=3.11 -y
conda activate reasoning_gym
```
``` 3. Install the package in editable mode:
conda create --name reasoning_gym python=3.11 -y ```bash
conda activate reasoning_gym pip install -e .
``` ```
3. Link project and install dependencies 4. Install development dependencies:
```bash
pip install -r requirements-dev.txt
```
``` ## Creating Procedural Datasets
pip install -e .
```
4. Install development dependencies When creating new datasets, please follow these guidelines:
``` 1. **Focus on Complex Problems**:
pip install -r requirements-dev.txt - Prioritize problems where guessing has a low probability of success (e.g., number multiplication)
``` - Avoid tasks with small answer sets (true/false, multiple-choice) as they create noisy rewards for RL
2. **Implementation Requirements**:
## Procedural Datasets - Create a configuration class
- Derive your dataset class from `ProceduralDataset` (see [dataset.py](https://github.com/open-thought/reasoning-gym/blob/main/reasoning_gym/dataset.py))
- We are primarily interested in problems/riddles for which guessing the answer has very little chance of success (good example: multiplying numbers). The problem of tasks with small sets of possible answers (like true/false, multiple-choice) is that RL has to deal with very noisy rewards, which makes it for learning faithful Chain-of-Thoughts. - Include comprehensive unit tests
- Each dataset should come with a configuration class, the dataset class derived from `ProceduralDataset` (see [dataset.py](https://github.com/open-thought/reasoning-gym/blob/main/reasoning_gym/dataset.py)) and unit tests. - Return dictionary items with keys: `"question"`, `"answer"`, and `"metadata"`
- All datasets return dict items with the keys `"question"`, `"answer"` and `"metadata"`. When no single good answer can be given set "answer" to `None`. - Use `None` for `"answer"` when multiple valid answers exist
- For non-trivial datasets override the `score_answer()` method which returns a numeric value in the range [0, 1] to indicate how close the result is to the actual result. - For complex datasets, implement the `score_answer()` method (return value range: [0, 1])
- take a look at a simple dataset implementation like [chain_sum.py](reasoning_gym/arithmetic/chain_sum.py) and [test_chain_sum.py](https://github.com/open-thought/reasoning-gym/blob/main/tests/test_chain_sum.py).
- provide clear instructions in the question prompt that would allow an average human to produce an asswer in the correct format. 3. **Getting Started**:
- Review example implementations:
- [chain_sum.py](reasoning_gym/arithmetic/chain_sum.py)
## Submitting Work - Pull-Requets - [test_chain_sum.py](https://github.com/open-thought/reasoning-gym/blob/main/tests/test_chain_sum.py)
- Write clear question prompts that an average human can understand and answer correctly
We're all working on different parts of reasoning-gym together. To make contributions smoothly we recommend the following:
## Pull Request Process
1. [Fork this project repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone it to your local machine. (Read more [About Forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks))
1. On a [new branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) in your fork (aka a "feature branch" and not `main`) work on a small focused change that only touches on a few files. 1. **Fork and Clone**:
1. Run `pre-commit` and make sure all files have formatting fixed. This simplifies life for reviewers. - [Fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
1. Package up a small bit of work that solves part of the problem - Clone your fork locally
[into a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) - Read more about [forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)
and
[send it out for review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). 2. **Create a Feature Branch**:
1. If you're lucky, we can merge your change into `main` without any problems. - Work on a [new branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository)
1. Merge in your change and move on to a new issue or the second step of your current issue. - Keep changes focused and minimal
3. **Code Quality**:
### Tips - Install pre-commit hooks: `pre-commit install`
- Run `pre-commit run -a` before committing
- To keep your PR clean don't include changes of `GALLERY.md` - the overview file is automatically updated regulary automatically - When using AI coding assistants (cursor, aider, etc.), ensure proper formatting
- install the pre-commit hook via `pre-commit install`
- when using AI coding assistants (cursor, aider, ..) please run `pre-commit run -a` to format all files before committing. 4. **Submit Your PR**:
- [Create a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
- [Request review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review)
- Do not include changes to `GALLERY.md` (it's updated automatically)
5. **Review Process**:
- Address reviewer feedback promptly
- Keep discussions constructive
- Once approved, your changes will be merged into `main`
## Need Help?
Join our community discussion in the `#reasoning-gym` channel on the [GPU-Mode Discord server](https://discord.gg/gpumode).