Pull Request Process

​

Before You Start

​

1. Discuss Your Changes

• 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

​

2. Set Up Your Environment

• 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

git checkout develop
git pull origin develop
git checkout -b feature/my-awesome-feature

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

​

Step 2: Make Your Changes

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

# 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

​

Step 4: Create Changelog Fragment

scriv create --edit

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

• 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

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"

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

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

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

​

Code Review

• 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

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

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

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

git merge develop
git push origin feature/my-awesome-feature

​

Pull Request Requirements

​

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

# Fix automatically
yarn run lint --fix
prettier --write .
black cvat/
isort cvat/

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

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

​

Merge Conflicts

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

• 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! 🎉

​

What’s Next?

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

​

Getting Help

• 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