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

# Pull Request Process

> How to create and submit pull requests for CVAT

This guide walks you through the process of creating, submitting, and getting your pull requests merged into CVAT.

## Before You Start

### 1. Discuss Your Changes

Before starting significant work:

* **Open an issue** or comment on an existing one to discuss your proposed changes
* Get feedback from maintainers about your approach
* Ensure your changes align with project goals
* Avoid duplication of effort

This helps ensure your contribution will be accepted and saves everyone time.

### 2. Set Up Your Environment

Make sure you have:

* Forked the CVAT repository
* Set up your [development environment](/contributing/development-environment)
* Read the [code style guidelines](/contributing/code-style)
* Familiarized yourself with [testing](/contributing/testing)

## Creating a Pull Request

### Step 1: Create a Branch

Create a feature branch from `develop`:

```bash theme={null}
git checkout develop
git pull origin develop
git checkout -b feature/my-awesome-feature
```

Branch naming conventions:

* `feature/description` - New features
* `fix/description` - Bug fixes
* `refactor/description` - Code refactoring
* `docs/description` - Documentation changes

### Step 2: Make Your Changes

Follow these guidelines:

1. **Write clean code**: Follow the [code style guidelines](/contributing/code-style)
2. **Keep commits focused**: Each commit should represent a logical change
3. **Write good commit messages**: See examples below
4. **Add tests**: Cover your changes with appropriate tests
5. **Update documentation**: If your changes affect user-facing features

### Step 3: Test Your Changes

Before submitting, ensure:

```bash theme={null}
# Run linters
yarn run lint
black cvat/
isort cvat/

# Run tests
pytest tests/python/
cd cvat-ui && yarn test

# Run E2E tests if UI changed
cd tests && yarn run cypress:run
```

See the [testing guide](/contributing/testing) for more details.

### Step 4: Create Changelog Fragment

CVAT uses [scriv](https://scriv.readthedocs.io/) for changelog management.

Create a changelog fragment:

```bash theme={null}
scriv create --edit
```

This creates a new file in `changelog.d/` where you describe your changes:

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

- New feature that does something useful
  (<https://github.com/cvat-ai/cvat/pull/XXXX>)

### Fixed

- Bug that caused issues in certain scenarios
  (<https://github.com/cvat-ai/cvat/pull/XXXX>)
```

Categories:

* **Added**: New features
* **Changed**: Changes to existing functionality
* **Deprecated**: Features that will be removed
* **Removed**: Features that were removed
* **Fixed**: Bug fixes
* **Security**: Security-related changes

### Step 5: Commit Your Changes

Write clear, descriptive commit messages:

```bash theme={null}
git add .
git commit -m "Add video chapter support for frame navigation

Implemented ability to display video chapters in the frame player
and use them for navigation during annotation. Chapters are extracted
from video metadata and displayed as markers on the timeline.

Resolves #9924"
```

Good commit message format:

```
Short summary (50 chars or less)

Detailed explanation of what changed and why. Wrap at 72 characters.
Explain the problem being solved and why this approach was chosen.

- Multiple changes can use bullet points
- Reference issues: Fixes #123, Resolves #456
- Break lines at 72 characters for readability
```

### Step 6: Push to Your Fork

```bash theme={null}
git push origin feature/my-awesome-feature
```

### Step 7: Create Pull Request on GitHub

1. Go to your fork on GitHub
2. Click "Compare & pull request"
3. **Base branch**: `develop` (not `master`!)
4. **Head branch**: Your feature branch
5. Fill out the PR template

## Pull Request Template

When you create a PR, fill out this template:

```markdown theme={null}
### Motivation and context
Why is this change required? What problem does it solve?
If it fixes an open issue, link to it here.

Resolves #123

### How has this been tested?
Describe how you tested your changes:
- Test environment details
- Test cases run
- Areas of code affected

### Checklist
- [ ] I submit my changes into the `develop` branch
- [ ] I have created a changelog fragment
- [ ] I have updated the documentation accordingly
- [ ] I have added tests to cover my changes
- [ ] I have linked related issues

### License
- [ ] I submit my code changes under the same MIT License that covers the project
```

## Review Process

### What Happens Next

1. **Automated checks run**: CI/CD pipeline runs tests and linters
2. **Maintainers review**: Core team reviews your code
3. **Feedback provided**: You may receive comments and change requests
4. **You iterate**: Address feedback and push updates
5. **Approval**: Once approved, your PR will be merged

### CI/CD Checks

Your PR must pass all automated checks:

* ✅ **Linters**: ESLint, Pylint, Black, isort
* ✅ **Type checking**: TypeScript, mypy
* ✅ **Tests**: Unit, integration, E2E tests
* ✅ **Security**: CodeQL analysis
* ✅ **Build**: Docker images build successfully

If checks fail, review the logs and fix issues.

### Code Review

Reviewers will check for:

* **Code quality**: Readable, maintainable, follows style guidelines
* **Correctness**: Logic is sound and bug-free
* **Tests**: Adequate test coverage
* **Documentation**: Changes are documented
* **Performance**: No unnecessary performance degradation
* **Security**: No security vulnerabilities introduced

### Responding to Feedback

When you receive feedback:

1. **Be responsive**: Reply to comments promptly
2. **Ask questions**: If something is unclear, ask for clarification
3. **Make changes**: Address the feedback in new commits
4. **Be respectful**: Remember reviewers are helping improve your code
5. **Mark resolved**: Mark conversations as resolved when addressed

Push updates:

```bash theme={null}
git add .
git commit -m "Address review feedback

- Fix type annotation issues
- Add missing test cases
- Update documentation"
git push origin feature/my-awesome-feature
```

### Updating Your Branch

If `develop` has moved forward, you may need to update:

```bash theme={null}
git checkout develop
git pull origin develop
git checkout feature/my-awesome-feature
git rebase develop
git push origin feature/my-awesome-feature --force-with-lease
```

Alternatively, merge instead of rebase:

```bash theme={null}
git merge develop
git push origin feature/my-awesome-feature
```

## Pull Request Requirements

Your PR should:

### Required

* [ ] Target the `develop` branch
* [ ] Pass all CI/CD checks
* [ ] Include a changelog fragment
* [ ] Have clear commit messages
* [ ] Include tests for new functionality
* [ ] Follow code style guidelines
* [ ] Link to related issues
* [ ] Have an approved review from a maintainer

### Recommended

* [ ] Update documentation if needed
* [ ] Add screenshots for UI changes
* [ ] Include performance considerations
* [ ] Address any security implications

## Common Issues

### CI Failures

**Linter errors:**

```bash theme={null}
# Fix automatically
yarn run lint --fix
prettier --write .
black cvat/
isort cvat/
```

**Test failures:**

* Run tests locally to reproduce
* Check test logs in CI for details
* Ensure your changes don't break existing functionality

**Build failures:**

* Check Docker build logs
* Ensure all dependencies are installed
* Verify Dockerfile syntax

### Merge Conflicts

If your branch has conflicts with `develop`:

```bash theme={null}
git checkout develop
git pull origin develop
git checkout feature/my-awesome-feature
git rebase develop
# Resolve conflicts in your editor
git add .
git rebase --continue
git push origin feature/my-awesome-feature --force-with-lease
```

### Stale Pull Requests

If your PR becomes stale:

* Update your branch with latest `develop`
* Address any new conflicts
* Respond to pending review comments
* Ping maintainers if needed

## After Your PR is Merged

### Clean Up

```bash theme={null}
git checkout develop
git pull origin develop
git branch -d feature/my-awesome-feature
git push origin --delete feature/my-awesome-feature
```

### Celebrate! 🎉

Your contribution is now part of CVAT! Thank you for contributing.

### What's Next?

* Look for more issues to work on
* Help review other pull requests
* Improve documentation
* Join community discussions

## Getting Help

If you need help with your PR:

* **Comment on the PR**: Ask questions directly
* **Join Gitter**: [opencv-cvat/public](https://gitter.im/opencv-cvat/public)
* **Join Discord**: [CVAT Discord Server](https://discord.gg/fNR3eXfk6C)
* **Check documentation**: Review relevant guides

## Best Practices

### Do:

* Keep PRs focused and reasonably sized
* Write clear descriptions and commit messages
* Add tests for your changes
* Update documentation when needed
* Respond to reviews promptly
* Be patient and respectful

### Don't:

* Submit massive PRs that are hard to review
* Make unrelated changes in the same PR
* Push without running tests locally
* Ignore review feedback
* Force-push over others' commits
* Be discouraged by feedback

## Resources

* [GitHub Pull Request Documentation](https://docs.github.com/en/pull-requests)
* [CVAT Contributing Guide](https://docs.cvat.ai/docs/contributing/)
* [Code Style Guidelines](/contributing/code-style)
* [Testing Guide](/contributing/testing)
* [Architecture Overview](/contributing/architecture)

Thank you for contributing to CVAT! Your efforts help make CVAT better for everyone.