Skip to content

docs(contributing): streamline contribution guides #302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ooooo-create wants to merge 4 commits into
base: main
Choose a base branch
from
+153 −178
Open

docs(contributing): streamline contribution guides #302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fa6f686
docs(contributing): clarify fork and lint workflow
ooooo-create Sep 7, 2026
0049753
docs(contributing): streamline contribution guides
ooooo-create Sep 9, 2026
2e30a71
Update docs/zh/guide/how-to-contribute.md
ooooo-create Sep 9, 2026
3a22c7d
apply review
ooooo-create Sep 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 15 additions & 56 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,13 @@ Thank you for your interest in contributing to Relax! This document provides gui

- [Code of Conduct](#code-of-conduct)
- [How Can I Contribute?](#how-can-i-contribute)
- [Development Setup](#development-setup)
- [Development Workflow](#development-workflow)
- [Developing](#developing)
- [Code Style](#code-style)
- [Commit Conventions](#commit-conventions)
- [Pull Request Process](#pull-request-process)
- [Reporting Bugs](#reporting-bugs)
- [Requesting Features](#requesting-features)
- [Community](#community)
- [License](#license)

## Code of Conduct
Expand All @@ -38,58 +38,17 @@ This project follows a standard code of conduct. Please be respectful, inclusive
- **Examples** — Add new training examples or tutorials
- **Testing** — Improve test coverage and add integration tests

## Development Setup
## Developing

```bash
# Clone the repository
git clone https://github.com/redai-studio/Relax.git
cd Relax
Follow the [development workflow](docs/en/guide/how-to-contribute.md#developing) for step-by-step commands:

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .
```

## Development Workflow

### 1. Create a Branch

```bash
# Feature
git checkout -b feature/your-feature-name

# Bug fix
git checkout -b fix/your-bug-fix

# Documentation
git checkout -b docs/your-doc-change
```

### 2. Make Changes

- Follow existing code patterns and conventions
- Add or update tests for your changes
- Update documentation if applicable (both English and Chinese)

### 3. Validate

```bash
# Run pre-commit checks (lint + format)
pre-commit run --all-files

# Run tests
pytest tests/
```

### 4. Submit a Pull Request

Push your branch and open a PR against `main`. Fill out the PR template completely.
1. Fork and clone the repository, add `upstream`, and sync your local `main`.
2. Set up the development environment and install Relax in editable mode.
3. Run the [DeepEyes example](docs/en/examples/deepeyes.md) to verify the training environment.
4. Create a working branch and install Git hooks with pre-commit.
5. Make your changes, add or update tests, and run the relevant unit tests. Update both language versions of the documentation when needed.
6. Review, stage, and commit your changes using [Conventional Commits](#commit-conventions). Git hooks run automatically on commit; review any fixes and stage them again before retrying.
7. Push your working branch to your fork and open a PR targeting `redai-studio/Relax`'s `main` branch. Fill out the [PR template](.github/PULL_REQUEST_TEMPLATE.md).

## Code Style

Expand Down Expand Up @@ -133,11 +92,11 @@ feat(rollout): add streaming data consumption for async mode

### Before Submitting

- [ ] Code compiles and runs without errors
- [ ] `pre-commit run --all-files` passes
- [ ] Tests pass (`pytest tests/`)
- [ ] Relevant tests pass locally
- [ ] Git hooks pass and code is formatted
- [ ] Documentation updated (if applicable)
- [ ] Commit messages follow Conventional Commits
- [ ] Branch is up to date with `main`

### PR Review

Expand All @@ -149,7 +108,7 @@ feat(rollout): add streaming data consumption for async mode
### Tips for a Good PR

- Keep PRs focused and reasonably sized
- Provide a clear description of **what**, **why**, and **how**
- Provide a clear description of **what**, **why**, **how**, and **testing**
- Link related issues (e.g., `Fixes #123`)
- Add screenshots or logs for UI or behavior changes

Expand Down
110 changes: 50 additions & 60 deletions docs/en/guide/how-to-contribute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,32 @@

Thank you for your interest in contributing to Relax! This guide will help you get started.

## Getting Started
## Developing

### 1. Set Up Development Environment
### 1. Get the Code

Create a virtual environment and install dependencies:
**Fork** [redai-studio/Relax](https://github.com/redai-studio/Relax) on GitHub, then clone your fork locally. Replace `<your_user_name>` with your GitHub username:

```bash
# Clone the repository
git clone https://github.com/redai-studio/Relax.git
git clone https://github.com/<your_user_name>/Relax.git
cd Relax
git remote add upstream https://github.com/redai-studio/Relax.git

# Create virtual environment
# Sync with the main branch of the upstream repository
git checkout main
git pull upstream main
```

`origin` points to your fork, and `upstream` points to the Relax repository. For subsequent contributions, switch to your local `main` and pull upstream updates before creating a working branch. Develop on working branches and keep your local `main` for syncing with upstream.

### 2. Set Up the Development Environment

See the [installation guide](./installation.md) for environment requirements.

```bash
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
Expand All @@ -24,16 +36,6 @@ pip install -r requirements.txt
pip install -e .
```

### 2. Start Ray and Deploy Services

```bash
# Start Ray cluster
ray start --head

# Deploy all services
python -m relax.core.controller deploy --config configs/env.yaml
```

### 3. Run Example Experiment

```bash
Expand All @@ -45,64 +47,50 @@ cd examples/deepeyes
bash run_deepeyes.sh
```

## Development Workflow

### 1. Create a Branch
### 4. Start Developing

```bash
# Create a feature branch
git checkout -b feature/your-feature-name
git checkout -b feature/your-change
```

# Or a bugfix branch
git checkout -b fix/your-bug-fix
Install pre-commit and Git hooks:

```bash
pip install pre-commit
pre-commit install
Comment on lines +56 to +60
```

### 2. Make Changes
Once installed, checks run automatically on each `git commit`.

- Write clean, readable code
- Follow the existing code style
- Add tests for new features
- Update documentation as needed
### 5. Run Unit Tests

### 3. Run Tests
After changing the code, add tests for new or fixed behavior and choose the test scope appropriate for your changes:

```bash
# Run all tests
pytest tests/

# Run specific test file
# Run a specific test file
pytest tests/utils/test_metrics_service.py

# Run with coverage
pytest --cov=relax tests/
```

### 4. Format Code

```bash
# Format with black
black relax/

# Sort imports
isort relax/

# Run linter
flake8 relax/
```
### 6. Commit Changes

### 5. Commit Changes
After completing the relevant validation, review your changes and stage the files you intend to commit. Replace `<changed-files>` with actual paths, separated by spaces:

```bash
# Stage changes
git add .

# Commit with descriptive message
git commit -m "feat: add new feature"
# or
git commit -m "fix: resolve bug in metrics service"
git status
git diff
git add <changed-files>
git commit -m "feat: describe your change"
```

Follow [Conventional Commits](https://www.conventionalcommits.org/):
If a hook modifies files or reports errors, review and fix the changes, then run `git add` and `git commit` again until the checks pass and the commit succeeds.

Follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:

- `feat:` - New feature
- `fix:` - Bug fix
Expand All @@ -112,15 +100,16 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/):
- `test:` - Adding or updating tests
- `chore:` - Maintenance tasks

### 6. Push and Create Pull Request
### 7. Open a PR

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

# Create pull request on GitHub
git push origin feature/your-change
```

On GitHub, open a PR from your working branch in your fork to **`main` in `redai-studio/Relax`**, and fill out the [PR template](https://github.com/redai-studio/Relax/blob/main/.github/PULL_REQUEST_TEMPLATE.md). Replace the branch name in the command if you chose a different one.

Address CI results and review feedback on the same branch, then check, commit, and push your changes. The PR updates automatically.

## Code Style Guidelines

### Python Style
Expand Down Expand Up @@ -167,7 +156,6 @@ def compute_reward(
### Writing Tests

```python
import pytest
from relax.utils.metrics.client import MetricsClient

def test_metrics_client_log_metric():
Expand All @@ -191,13 +179,15 @@ def test_metrics_client_log_metric():

### Adding Documentation

1. Add markdown files to `docs/guide/` or `docs/zh/guide/`
2. Update `.vitepress/config.mts` to add to sidebar
1. Add markdown files to `docs/en/guide/` or `docs/zh/guide/`
2. Update `docs/.vitepress/config.mts` to add to sidebar
3. Include code examples and diagrams
4. Provide both English and Chinese versions

### Building Documentation

Install Node.js, then run the following commands from the repository root:

```bash
# Start documentation dev server
make docs-dev
Expand Down
Loading