> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Raising a Pull Request

> Guidelines for submitting high-quality pull requests to Bifrost.

## Before You Start

1. **Create an issue first** (if one doesn't exist) - Discuss the change with the maintainers
2. **Fork the repository** and create a feature branch from `dev` (the default development branch; `main` is reserved for releases). Target `dev` when opening your PR.
3. **Set up your development environment** using [these instructions](/contributing/setting-up-repo)
4. **Run tests locally** to ensure everything works

## Commit Message Format

All commits should follow a standardized format. **For each package/directory you modify, include a separate commit message line** describing the change in that package.

### Format

```
[type]: description

Additional details if needed (optional)
```

### Types

* **feat** - New feature
* **fix** - Bug fix
* **refactor** - Code refactoring (no feature change, no bug fix)
* **docs** - Documentation changes
* **test** - Test changes
* **chore** - Build, dependencies, tooling changes
* **perf** - Performance improvements

### Examples

**Single Package Change:**

```
[fix]: handle connection timeout in MCP client manager
```

**Multiple Packages:**
If your change affects multiple packages, include the package name or affected module in the description:

```
[fix]: MCP client - add retry logic to connection establishment

This fixes intermittent connection failures by implementing exponential backoff.
Affected packages:
- core/mcp/clientmanager.go
- core/mcp/healthmonitor.go
```

**Provider-Specific Changes:**

```
[fix]: OpenAI provider - handle streaming response errors
[feat]: Anthropic provider - add support for batch API
```

**Multiple Commits for Multiple Packages:**
If you're making significant changes to multiple packages, consider separate commits:

```bash theme={null}
git commit -m "[feat]: Add retry mechanism to MCP core utilities"
git commit -m "[fix]: Update OpenAI integration with retry support"
git commit -m "[docs]: Document MCP resilience strategy"
```

### All Packages Modified Should Be Listed

When creating a commit, always mention which packages/components are affected:

```
[feat]: Add semantic caching plugin

Changes:
- plugins/semanticcache/ - Core caching logic
- core/bifrost.go - Plugin registration
- transports/bifrost-http/server.go - Cache middleware integration

Benefits:
- Reduces API costs by 30-40%
- Improves response latency for similar queries
```

<Tip>
  Use a structured format that makes it easy to understand at a glance what changed and where.
</Tip>

## Maintaining Changelogs

For each package you modify, update the corresponding `changelog.md` file with your changes. Changelog entries are used to generate release notes and communicate changes to users.

### Changelog File Locations

Each package that receives updates should have a `changelog.md` file:

* `core/changelog.md` - Core package changes
* `framework/changelog.md` - Framework changes
* `transports/changelog.md` - Transport layer changes
* `plugins/{plugin-name}/changelog.md` - Specific plugin changes

### Changelog Entry Format

Each changelog entry follows this exact format:

```
[type]: description [@Your Name](https://github.com/yourname)
```

**Required Components:**

* **Type**: One of `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, or `perf`
* **Description**: Clear, concise description (under 100 characters)
* **Author**: Your GitHub profile link (recommended)

### Change Types Reference

| Type         | Usage                                 | Example                                            |
| ------------ | ------------------------------------- | -------------------------------------------------- |
| **feat**     | New feature                           | `[feat]: add exponential backoff retry mechanism`  |
| **fix**      | Bug fix                               | `[fix]: handle connection timeout in MCP client`   |
| **refactor** | Code refactoring (no behavior change) | `[refactor]: simplify model caching`               |
| **docs**     | Documentation updates                 | `[docs]: clarify semantic caching behavior`        |
| **test**     | Test additions/modifications          | `[test]: add regression tests for retry logic`     |
| **chore**    | Build, dependencies, tooling          | `[chore]: upgrade dependencies to latest versions` |
| **perf**     | Performance improvements              | `[perf]: optimize model lookup to O(1)`            |

### Changelog Examples

**Good Examples:**

```markdown theme={null}
[feat]: add exponential backoff retry mechanism [@prathammaxim](https://github.com/prathammaxim)
[fix]: handle null pointer in OpenAI response parsing [@contributor](https://github.com/contributor)
[perf]: optimize model lookup with hash map [@contributor](https://github.com/contributor)
```

**Poor Examples (avoid):**

```markdown theme={null}
- update stuff
- minor changes
- fix bug
- added new thing
```

### How to Add Changelog Entries

1. **Edit the `changelog.md`** file in the affected package
2. **Add new entry at the TOP** of the file (most recent first)
3. **Follow the exact format**: `[type]: description [@name](https://github.com/user)`
4. **Include your author link** (optional but recommended)

**Example: Before and After**

**Before:**

```markdown theme={null}
[feat]: added image generation request and response support
[chore]: added case-insensitive helper methods
```

**After (with new entry at top):**

```markdown theme={null}
[fix]: handle connection timeout in retry logic [@your-name](https://github.com/your-name)
[feat]: add exponential backoff for transient errors [@your-name](https://github.com/your-name)
[feat]: added image generation request and response support
[chore]: added case-insensitive helper methods
```

### Multiple Package Changes

When your PR affects multiple packages, **add entries to each package's `changelog.md`**:

**Example Multi-Package Changelog:**

**core/changelog.md:**

```markdown theme={null}
[feat]: add retry executor with exponential backoff [@contributor](https://github.com/contributor)
```

**transports/changelog.md:**

```markdown theme={null}
[fix]: apply retry logic to connection establishment [@contributor](https://github.com/contributor)
```

**plugins/governance/changelog.md:**

```markdown theme={null}
[chore]: update core dependency to latest version
```

### What to Include in Changelog

✅ **Do include:**

* Bug fixes that affect users
* New features
* Breaking changes
* Performance improvements
* Significant refactoring
* Documentation improvements

❌ **Don't include:**

* Internal code cleanup with no user impact
* Typo fixes in comments only
* Build system changes (unless significant)
* Minor test-only changes

### Changelog Best Practices

1. **Add entries at the TOP** of the `changelog.md` file (most recent first)
2. **One entry per logical change** - Don't combine unrelated changes
3. **Keep descriptions concise** - Under 100 characters
4. **Use consistent format** - `[type]: description`
5. **Include your GitHub link** - Helps recognize contributors
6. **Update all affected package changelogs** - Don't forget secondary packages
7. **Add changelog entry with your commit** - Don't wait until the end

### Format Consistency Rules

**DO's:**

* ✅ Use square brackets: `[feat]`
* ✅ Use colon separator: `[feat]:`
* ✅ Start with lowercase (unless proper noun)
* ✅ Be specific and concise
* ✅ Include GitHub profile link
* ✅ Add new entries at the top

**DON'Ts:**

* ❌ Don't use parentheses: `(feat)` or braces `{feat}`
* ❌ Don't use multiple spaces
* ❌ Don't mix formats in the same file
* ❌ Don't add entries at the bottom
* ❌ Don't use vague descriptions

### Complete PR Example with Changelogs

If your PR adds retry logic to multiple packages:

```
Commit: [feat]: Add retry logic with exponential backoff

Modified files:
- core/mcp/utils.go ← add retry executor
- core/mcp/clientmanager.go ← use retry logic

Update changelogs:

1. core/changelog.md:
   [feat]: add exponential backoff retry mechanism [@your-name](https://github.com/your-name)

2. transports/changelog.md:
   [fix]: apply retry logic to connection establishment [@your-name](https://github.com/your-name)
```

### Changelog Review Checklist

Before submitting a PR, verify:

* [ ] All packages modified have changelog entries
* [ ] Format is correct: `[type]: description [@name](https://github.com/user)`
* [ ] Entries are added at TOP of the file
* [ ] Author GitHub link is included
* [ ] Description is clear and concise (under 100 chars)
* [ ] Type is one of: feat, fix, refactor, docs, test, chore, perf
* [ ] Entries are added with the commit (not after)

## Pull Request Title

Keep PR titles concise and descriptive, following the same pattern:

```
[type]: Brief description of the change
```

Examples:

* `[feat]: Add rate limiting to governance plugin`
* `[fix]: Resolve deadlock in MCP retry logic`
* `[refactor]: Simplify model caching mechanism`
* `[docs]: Update contribution guidelines for commit messages`

## Pull Request Description

Use the following template for your PR description:

```markdown theme={null}
## Description

Brief explanation of what this PR does and why it's needed.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
- [ ] Refactoring

## Affected Packages

List all packages/directories modified:
- core/providers/openai/
- transports/bifrost-http/server/
- plugins/governance/

## Changes Made

- Specific change 1
- Specific change 2
- Specific change 3

## Testing

Describe how you tested these changes:
- [ ] Unit tests added/updated
- [ ] Integration tests passed
- [ ] Manual testing completed

## Checklist

- [ ] Code follows the project's code style
- [ ] Tests are passing locally (`make test-all`)
- [ ] Documentation is updated if needed
- [ ] No breaking changes (or breaking changes are documented)
- [ ] Commit messages follow the format: `[type]: description`
- [ ] All affected packages are mentioned in commit messages

## Related Issues

Closes #123
Relates to #456
```

## Best Practices

### 1. Keep PRs Focused

* One feature or fix per PR when possible
* If multiple related changes, group them logically by package
* Avoid mixing refactoring with feature changes

### 2. Commit Messages Matter

❌ **Bad:**

```
Update file
```

✅ **Good:**

```
[fix]: Handle null pointer in OpenAI response parsing
```

❌ **Bad:**

```
[feat]: Major update to semantic cache
```

✅ **Good:**

```
[feat]: Add semantic cache initialization with retry logic

Changes:
- plugins/semanticcache/ - Add retry mechanism
- core/bifrost.go - Register cache handler
- docs/ - Add usage documentation
```

### 3. Include All Affected Packages

Always explicitly list which packages/directories are modified:

```
[fix]: Resolve SSE connection issues

Affected components:
- core/mcp/clientmanager.go - Add connection validation
- core/mcp/healthmonitor.go - Improve health checks
- core/mcp/utils.go - Fix retry context handling
```

### 4. Test Thoroughly

Before opening a PR:

```bash theme={null}
# Run all tests
make test-all

# Run specific test suite
make test-core PROVIDER=openai

# Format code
make fmt

# Lint code
make lint
```

### 5. Small, Reviewable PRs

* Aim for \<400 lines changed per PR
* If larger, break into logical commits
* Each commit should be independently reviewable

### 6. Update Documentation

* Update relevant `.mdx` files in `/docs`
* Add comments for complex logic
* Update README.md if behavior changes

## Code Review Checklist

Before requesting review, ensure:

✅ All commits follow `[type]: description` format
✅ All affected packages are explicitly mentioned
✅ No merge conflicts
✅ All tests pass (`make test-all`)
✅ Code is properly formatted (`make fmt`)
✅ No linting issues (`make lint`)
✅ Documentation is updated
✅ PR description is clear and complete

## During Code Review

* Respond to feedback promptly
* Push new commits for requested changes (don't force-push to avoid confusion)
* Mark conversations as resolved when addressed
* Ask for clarification if feedback is unclear

## Merging

Once approved:

* The maintainer will handle the merge
* Your commits will be preserved in the history
* Ensure your branch is up-to-date with `dev` before final approval

## Common Pitfalls to Avoid

1. ❌ **Vague commit messages** - Always be specific about what changed
2. ❌ **Missing package information** - Always list affected packages
3. ❌ **Mixing concerns** - Keep commits focused
4. ❌ **Not running tests** - Test locally before opening PR
5. ❌ **Large PRs** - Break into smaller, reviewable chunks
6. ❌ **Not updating docs** - If behavior changes, update documentation

## Examples of Good Commits

### Example 1: Provider Fix

```
[fix]: OpenAI provider - handle streaming response errors correctly

Previously, streaming responses would sometimes fail with
"context deadline exceeded" error when network latency exceeded
timeout threshold.

Changes:
- core/providers/openai/openai.go - Add dynamic timeout
- core/providers/anthropic/anthropic.go - Align timeout logic
- tests/ - Add regression tests

Affected packages:
- core/providers/
- core/bifrost.go (minor type update)
```

### Example 2: Plugin Development

```
[feat]: Add rate limiting to governance plugin

Introduces token bucket algorithm for per-customer rate limiting.
Allows fine-grained control over request throughput.

Changes:
- plugins/governance/ratelimit/ - New package with core logic
- plugins/governance/main.go - Register rate limiter
- transports/bifrost-http/middleware.go - Apply rate limit checks
- docs/features/governance.mdx - Add usage documentation

Benefits:
- Prevents request storms
- Fair resource allocation
- Configurable per-customer
```

### Example 3: Core Refactoring

```
[refactor]: Simplify model caching to reduce complexity

Consolidate three separate caching layers into unified approach.
No behavior change - internal improvement only.

Changes:
- core/models.go - Unified cache implementation
- core/cache/ - Remove legacy cache package
- tests/ - Update cache tests

Affected packages:
- core/ (main change)
- plugins/ (minor - cache API unchanged)
```

## Need Help?

* 📚 See [Code Conventions](/contributing/code-conventions) for style guidelines
* 🏗️ Check [Architecture Docs](/architecture) to understand the codebase structure
* 💬 Ask in [Discord](https://discord.gg/exN5KAydbU) if unsure about the process
* ❓ Refer to the [Changelog Review Checklist](#changelog-review-checklist) above before submitting