Contribution Guide

How to contribute to Bitwarden Server

Thank you for your interest in contributing to Bitwarden Server! This guide will help you make your first contribution.

Before You Start

Bitwarden has comprehensive contributing documentation available at:

contributing.bitwarden.com

This official documentation includes:

• Detailed contribution guidelines
• Code style requirements
• Architecture documentation
• Database migration guides
• PR review process

Bitwarden Server is licensed under the AGPL 3.0 license (see LICENSE_AGPL.txt). By contributing, you agree that your contributions will be licensed under the same terms.

Quick Start for Contributors

1. Fork and clone the repository

   # Fork the repository on GitHub first, then:
   git clone https://github.com/YOUR_USERNAME/server.git
   cd server
   git remote add upstream https://github.com/bitwarden/server.git
   
2. Set up your development environment

   Follow the Local Development Setup guide to configure your environment.

3. Create a feature branch

   git checkout -b feature/my-contribution
   

   Branch naming conventions:

   • feature/description - New features
   • bugfix/description - Bug fixes
   • refactor/description - Code refactoring
   • docs/description - Documentation updates
4. Make your changes

   Ensure your code follows the project’s:

   • Code style guidelines
   • Testing requirements
   • Security guidelines
5. Test your changes

   # Run affected tests
   dotnet test test/Core.Test/
   
   # Run integration tests if applicable
   dotnet test test/Api.IntegrationTest/
   
6. Commit your changes

   Use clear, descriptive commit messages:

   git add .
   git commit -m "Add user preference storage feature
   
   Implements user preferences storage with encrypted JSON.
   Adds new User.Preferences column and repository methods.
   
   Fixes #1234"
   

   Commit message format:

   • First line: Brief summary (50 chars or less)
   • Blank line
   • Detailed description of changes
   • Reference issue numbers
7. Push and create a pull request

   git push origin feature/my-contribution
   

   Then create a PR on GitHub targeting the main branch.

Pull Request Guidelines

PR Title

Use a clear, descriptive title:

Add user preferences storage
Fix cipher export bug for organizations
Refactor authentication service
Update database migration documentation

PR Description Template

Provide a comprehensive description:

## Type of Change
- [ ] Bug fix
- [x] New feature
- [ ] Breaking change
- [ ] Documentation update

## Description
Adds support for storing user UI preferences in the database.
Preferences are stored as encrypted JSON in a new User.Preferences column.

## Changes Made
- Added `Preferences` column to User table
- Created database migration script
- Added repository methods for preference CRUD
- Implemented preference encryption/decryption
- Added unit and integration tests

## Testing
- [x] Unit tests added
- [x] Integration tests added
- [x] Manual testing completed

## Related Issues
Fixes #1234
Related to #5678

## Screenshots (if applicable)
[Add screenshots here]

## Checklist
- [x] Code follows project style guidelines
- [x] Tests pass locally
- [x] Documentation updated
- [x] Database migrations added (if applicable)

PR Size

Keep PRs focused and manageable:

Ideal PR:

• Single feature or bug fix
• 200-400 lines changed
• Easy to review

Large PR (avoid if possible):

• Multiple features
• 1000+ lines changed
• Difficult to review

If your change is large, consider:

1. Breaking it into smaller PRs
2. Creating a tracking issue for the overall feature
3. Linking PRs together

Code Review Process

What to Expect

1. Automated Checks: CI/CD runs tests and linting
2. Initial Review: Maintainer reviews within 1-2 weeks
3. Feedback: You may receive change requests
4. Updates: Address feedback and push updates
5. Approval: Once approved, maintainers will merge

Responding to Feedback

# Make requested changes
git add .
git commit -m "Address PR feedback

- Update error handling as requested
- Add missing unit tests
- Fix code style issues"

git push origin feature/my-contribution

CI/CD Checks

Your PR must pass:

• Build - Code compiles successfully
• Tests - All unit and integration tests pass
• Linting - Code style checks pass
• Security Scan - No security vulnerabilities

Common Contribution Types

Bug Fixes

1. Verify the bug

   Reproduce the issue locally and understand the root cause.

2. Write a failing test

   Create a test that demonstrates the bug:

   [Theory]
   [BitAutoData]
   public async Task GetCipher_DeletedCipher_ThrowsNotFoundException(
       SutProvider<CipherService> sutProvider,
       Cipher cipher)
   {
       cipher.DeletedDate = DateTime.UtcNow;
       
       sutProvider.GetDependency<ICipherRepository>()
           .GetByIdAsync(cipher.Id)
           .Returns(cipher);
       
       await Assert.ThrowsAsync<NotFoundException>(
           () => sutProvider.Sut.GetAsync(cipher.Id)
       );
   }
   
3. Fix the bug

   Implement the fix and ensure the test passes.

4. Submit PR

   Reference the issue number in your PR description.

New Features

1. Discuss first

   For significant features, open an issue to discuss the approach before implementing.

2. Design the feature

   • Identify affected entities
   • Plan database changes
   • Consider backward compatibility
3. Implement incrementally

   1. Database migration
   2. Repository layer
   3. Service layer
   4. API endpoints
   5. Tests
4. Document the feature

   Update relevant documentation and add code comments.

Database Changes

See Database Migrations for detailed guidance.

Checklist:

• Migration script is idempotent
• Migration tested locally
• Backward compatible (if possible)
• Rollback plan documented
• All database providers supported (SQL Server, PostgreSQL, MySQL)

Documentation Updates

Documentation improvements are always welcome:

• Fix typos and grammar
• Clarify confusing sections
• Add examples
• Update outdated information

# Documentation-only PRs
git checkout -b docs/improve-testing-guide
# Make changes to .md/.mdx files
git commit -m "Improve testing guide with more examples"

Coding Standards

See the Code Style Guide for detailed guidelines.

Key Points

C# Style:

// Good: Clear, descriptive names
public async Task<User> GetUserByEmailAsync(string email)
{
    if (string.IsNullOrWhiteSpace(email))
    {
        throw new BadRequestException("Email is required.");
    }
    
    return await _userRepository.GetByEmailAsync(email);
}

// Bad: Unclear, inconsistent style
public async Task<User> get(string e) {
    return await _userRepository.GetByEmailAsync(e);
}

File Organization:

src/Core/
├── Entities/          # Entity classes
├── Enums/             # Enumerations
├── Repositories/      # Repository interfaces
├── Services/          # Service interfaces
└── {Domain}/          # Domain-specific code
    ├── Entities/
    ├── Services/
    └── Repositories/

Git Workflow

Keeping Your Fork Updated

# Fetch upstream changes
git fetch upstream

# Update your main branch
git checkout main
git merge upstream/main
git push origin main

# Rebase your feature branch
git checkout feature/my-contribution
git rebase main

Handling Conflicts

# If rebase results in conflicts
git rebase main
# Fix conflicts in your editor
git add .
git rebase --continue

# Force push (only to your branch!)
git push origin feature/my-contribution --force-with-lease

Squashing Commits

Maintainers may ask you to squash commits:

# Interactive rebase to squash commits
git rebase -i HEAD~3  # Last 3 commits

# In the editor, change 'pick' to 'squash' for commits to combine
pick abc123 Initial implementation
squash def456 Fix typo
squash ghi789 Address PR feedback

# Edit the commit message
git push origin feature/my-contribution --force-with-lease

Pre-Commit Hooks

Enable automatic code formatting:

git config --local core.hooksPath .git-hooks

This runs dotnet format before each commit.

Testing Your Changes

Local Testing

# Build the solution
dotnet build

# Run unit tests
dotnet test test/Core.Test/

# Run integration tests
dotnet test test/Api.IntegrationTest/

# Run specific test
dotnet test --filter "FullyQualifiedName~UserServiceTests"

Manual Testing

1. Start required services:

   docker-compose -f .devcontainer/bitwarden_common/docker-compose.yml up -d
   

2. Run the API:

   cd src/Api
   dotnet run
   

3. Test your changes with a client application

Security Considerations

See Security Guidelines for detailed information.

Never commit:

• Passwords or API keys
• .env files with real credentials
• Secrets or private keys
• Personal information

Security-sensitive changes:

• Authentication/authorization
• Encryption/decryption
• Password handling
• API key management

These require extra scrutiny - discuss with maintainers first.

Reporting Security Vulnerabilities

DO NOT open public issues for security vulnerabilities.

Instead:

1. Report via HackerOne
2. Or email security concerns privately (see SECURITY.md)

Community Guidelines

Code of Conduct

Be respectful, constructive, and professional:

• Welcome newcomers
• Provide constructive feedback
• Be patient with questions
• Respect different opinions

Getting Help

• GitHub Issues - Bug reports and feature requests
• GitHub Discussions - Questions and general discussion
• Contributing Docs - https://contributing.bitwarden.com/

Recognition

Contributors are recognized in:

• GitHub contributor graphs
• Release notes (for significant contributions)
• Community forums

License

By contributing to Bitwarden Server, you agree that your contributions will be licensed under the AGPL 3.0 License.

Some components use the Bitwarden License - check the license header in files.

Resources

• Official Contributing Docs: https://contributing.bitwarden.com/
• Community Forums: https://community.bitwarden.com/
• GitHub Issues: https://github.com/bitwarden/server/issues
• Trademark Guidelines: TRADEMARK_GUIDELINES.md

Next Steps

• Local Development Setup - Set up your environment
• Code Style Guide - Learn the code standards
• Testing Guide - Write effective tests
• Security Guidelines - Understand security requirements