Skip to content

docs(contributing): update contributing setup instructions to reflect the uv migration #2354

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
Steeveyboy wants to merge 14 commits into
base: main
Choose a base branch
from
+41 −32
Open

docs(contributing): update contributing setup instructions to reflect the uv migration #2354

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
73e990a
docs(contributing): fix repository URLs from instructor-ai to 567-labs
Steeveyboy Jun 6, 2026
5d6ba17
docs(contributing): fix repository URLs from instructor-ai to 567-lab…
Steeveyboy Jun 6, 2026
610da6a
docs(contributing): replace pip install -e with uv sync in CONTRIBUTI…
Steeveyboy Jun 6, 2026
d6d1589
docs(contributing): replace pip install -e with uv sync in docs/contr…
Steeveyboy Jun 6, 2026
761168d
docs(contributing): replace pip install pre-commit with uv tool install
Steeveyboy Jun 6, 2026
2a1b6a6
docs(contributing): replace pip install pre-commit with uv tool insta…
Steeveyboy Jun 6, 2026
c260609
docs(contribute): Added step to create and activate uv environment in…
Steeveyboy Jun 7, 2026
3be6dd0
docs(contribute): Added step to create and activate uv environment in…
Steeveyboy Jun 7, 2026
7d498aa
docs(contributing): updated pytest instructing to use uv run
Steeveyboy Jun 7, 2026
6e2db87
docs(contributing): updated pytest instructions to use uv run in docs…
Steeveyboy Jun 7, 2026
103ba3b
docs(contributing): added uv lock as key command
Steeveyboy Jun 7, 2026
02fe513
docs(contributing): added .git to the end of repo url
Steeveyboy Jun 7, 2026
66e32db
docs: removed line to activate environment from CONTRIBUTE.md
Steeveyboy Jun 8, 2026
dede0e3
Merge branch 'main' into feature/updating_contribute_md
Steeveyboy Jun 30, 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
45 changes: 27 additions & 18 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ By participating in this project, you agree to abide by our code of conduct: tre

### Environment Setup

1. **Fork the Repository**: Click the "Fork" button at the top right of the [repository page](https://github.com/instructor-ai/instructor).
1. **Fork the Repository**: Click the "Fork" button at the top right of the [repository page](https://github.com/567-labs/instructor).

2. **Clone Your Fork**:
```bash
Expand All @@ -48,7 +48,7 @@ By participating in this project, you agree to abide by our code of conduct: tre

3. **Set up Remote**:
```bash
git remote add upstream https://github.com/instructor-ai/instructor.git
git remote add upstream https://github.com/567-labs/instructor.git
```

4. **Install UV** (recommended):
Expand All @@ -62,20 +62,28 @@ By participating in this project, you agree to abide by our code of conduct: tre

5. **Install Dependencies**:
```bash
# Using uv (recommended)
uv pip install -e ".[dev,docs,test-docs]"
# Create environment using uv (recommended)
uv venv

# Activate environment
source .venv/bin/activate

# Install with development dependencies
uv sync --extra dev --extra docs --extra test-docs

# OR

# Using poetry
poetry install --with dev,docs,test-docs

# For specific providers, add the provider name as an extra
# Example: uv pip install -e ".[dev,docs,test-docs,anthropic]"
# Example: uv sync --extra anthropic
```

6. **Set up Pre-commit**:
```bash
pip install pre-commit
pre-commit install
uv tool install pre-commit
uv run pre-commit install
```

### Development Workflow
Expand Down Expand Up @@ -115,17 +123,18 @@ UV is a fast Python package installer and resolver. It's recommended for day-to-
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project and development dependencies
uv pip install -e ".[dev,docs]"
uv sync --extra dev --extra docs

# Adding a new dependency (example)
uv pip install new-package
uv add <new-package>
```

Key UV commands:
- `uv pip install -e .` - Install the project in editable mode
- `uv pip install -e ".[dev]"` - Install with development extras
- `uv pip freeze > requirements.txt` - Generate requirements file
- `uv sync` - Install the project in editable mode and updates lockfile
- `uv sync --extra dev` - Install with development extras
- `uv export --no-hashes --no-emit-project --format requirements-txt -o requirements.txt` - Generate requirements file
- `uv self update` - Update UV to the latest version
- `uv lock` - Generate lockfile based off pyproject.toml

#### Using Poetry

Expand Down Expand Up @@ -173,7 +182,7 @@ Instructor uses optional dependencies to support different LLM providers. Provid
4. **Document Installation**: Update the documentation to include installation instructions:
```
# Install with your provider support
uv pip install "instructor[my-provider]"
uv add "instructor[my-provider]"
# or
poetry install --with my-provider
```
Expand All @@ -198,7 +207,7 @@ Instructor uses optional dependencies to support different LLM providers. Provid

### Reporting Bugs

If you find a bug, please create an issue on [our issue tracker](https://github.com/instructor-ai/instructor/issues) with:
If you find a bug, please create an issue on [our issue tracker](https://github.com/567-labs/instructor/issues) with:

1. A clear, descriptive title
2. A detailed description including:
Expand Down Expand Up @@ -241,7 +250,7 @@ Documentation improvements are always welcome! Follow these guidelines:

We encourage contributions to our evaluation tests:

1. Explore existing evals in the [evals directory](https://github.com/instructor-ai/instructor/tree/main/tests/llm)
1. Explore existing evals in the [evals directory](https://github.com/567-labs/instructor/tree/main/tests/llm)
2. Contribute new evals as pytest tests
3. Evals should test specific capabilities or edge cases of the library or models
4. Follow the existing patterns for structuring eval tests
Expand Down Expand Up @@ -350,13 +359,13 @@ Run tests using pytest:

```bash
# Run all tests
pytest tests/
uv run pytest tests/

# Run specific test
pytest tests/path_to_test.py::test_name
uv run pytest tests/path_to_test.py::test_name

# Skip LLM tests (faster for local development)
pytest tests/ -k 'not llm and not openai'
uv run pytest tests/ -k 'not llm and not openai'

# Generate coverage report
coverage run -m pytest tests/ -k "not docs"
Expand Down
34 changes: 20 additions & 14 deletions docs/contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ We welcome contributions to Instructor! This page covers the different ways you

Evals help us monitor the quality of both the OpenAI models and the Instructor library. To contribute:

1. **Explore Existing Evals**: Check out [our evals directory](https://github.com/instructor-ai/instructor/tree/main/tests/llm/test_openai/evals)

@Steeveyboy Steeveyboy Jun 7, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fix: this link lead to a 404 and was modified to point to the test_openai directory

1. **Explore Existing Evals**: Check out [our evals directory](https://github.com/567-labs/instructor/tree/main/tests/llm/test_openai)
2. **Create a New Eval**: Add new pytest tests that evaluate specific capabilities or edge cases
3. **Follow the Pattern**: Structure your eval similar to existing ones
4. **Submit a PR**: We'll review and incorporate your eval
Expand All @@ -22,7 +22,7 @@ Evals are run weekly, and results are tracked to monitor performance over time.

### Reporting Issues

If you encounter a bug or problem, please [file an issue on GitHub](https://github.com/instructor-ai/instructor/issues) with:
If you encounter a bug or problem, please [file an issue on GitHub](https://github.com/567-labs/instructor/issues) with:

1. A clear, descriptive title
2. Detailed information including:
Expand All @@ -38,8 +38,8 @@ If you encounter a bug or problem, please [file an issue on GitHub](https://gith
We welcome pull requests! Here's the process:

1. **For Small Changes**: Feel free to submit a PR directly
2. **For Larger Changes**: [Start with an issue](https://github.com/instructor-ai/instructor/issues) to discuss approach
3. **Looking for Ideas?** Check issues labeled [help wanted](https://github.com/instructor-ai/instructor/labels/help%20wanted) or [good first issue](https://github.com/instructor-ai/instructor/labels/good%20first%20issue)
2. **For Larger Changes**: [Start with an issue](https://github.com/567-labs/instructor/issues) to discuss approach
3. **Looking for Ideas?** Check issues labeled [help wanted](https://github.com/567-labs/instructor/labels/help%20wanted) or [good first issue](https://github.com/567-labs/instructor/labels/good%20first%20issue)

## Setting Up Your Development Environment

Expand All @@ -62,17 +62,23 @@ UV is a fast Python package installer and resolver that makes development easier
git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor

# Create a uv environment
uv venv

# Activate environment
source .venv/bin/activate

# Install with development dependencies
uv pip install -e ".[dev,docs]"
uv sync --extra dev --extra docs
```

3. **Adding New Dependencies**:
```bash
# Add a regular dependency
uv pip install some-package
uv add some-package

# Install a specific version
uv pip install "some-package>=1.0.0,<2.0.0"
uv add "some-package>=1.0.0,<2.0.0"
```

4. **Common UV Commands**:
Expand All @@ -81,7 +87,7 @@ UV is a fast Python package installer and resolver that makes development easier
uv self update

# Create a requirements file
uv pip freeze > requirements.txt
uv export --no-hashes --no-emit-project --format requirements-txt -o requirements.txt
```

### Using Poetry
Expand Down Expand Up @@ -142,7 +148,7 @@ Instructor uses optional dependencies to support different LLM providers. Provid
4. **Document Installation**:
```bash
# Installation command for your provider
uv pip install "instructor[my-provider]"
uv add "instructor[my-provider]"
# or with poetry
poetry install --with my-provider
```
Expand Down Expand Up @@ -171,7 +177,7 @@ Instructor uses optional dependencies to support different LLM providers. Provid
```bash
git clone https://github.com/YOUR-USERNAME/instructor.git
cd instructor
git remote add upstream https://github.com/instructor-ai/instructor.git
git remote add upstream https://github.com/567-labs/instructor.git
```
3. **Create a Branch**:
```bash
Expand All @@ -180,7 +186,7 @@ Instructor uses optional dependencies to support different LLM providers. Provid
4. **Make Changes, Test, and Commit**:
```bash
# Run tests
pytest tests/ -k 'not llm and not openai' # Skip LLM tests for faster local dev
uv run pytest tests/ -k 'not llm and not openai' # Skip LLM tests for faster local dev

# Commit changes
git add .
Expand Down Expand Up @@ -300,8 +306,8 @@ We use the following tools to maintain code quality:

```bash
# Install pre-commit hooks
pip install pre-commit
pre-commit install
uv tool install pre-commit
uv run pre-commit install
```

Key style guidelines:
Expand Down Expand Up @@ -439,7 +445,7 @@ print(person.age) # 25

<!-- ALL-CONTRIBUTORS-LIST:END -->

<a href="https://github.com/instructor-ai/instructor/graphs/contributors">
<a href="https://github.com/567-labs/instructor/graphs/contributors">
<img src="https://contrib.rocks/image?repo=jxnl/instructor" />
</a>

Expand Down