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
• Read the code style guidelines
• Familiarized yourself with testing

Creating a Pull Request

Step 1: Create a Branch

Create a feature branch from develop:

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
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:

# 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 for more details.

Step 4: Create Changelog Fragment

CVAT uses scriv for changelog management.

Create a changelog fragment:

scriv create --edit

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

### 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:

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

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:

### 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:

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:

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:

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:

# 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:

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

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
• Join Discord: CVAT Discord Server
• 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
• CVAT Contributing Guide
• Code Style Guidelines
• Testing Guide
• Architecture Overview

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