# Review Board Cloudron Package

## Description

Review Board is a web-based code and document review tool. It tracks pending code, graphics, documents, and all discussions around decisions made about your product. It helps companies and organizations maintain code quality and keep bug counts low.

## Features

### Core Capabilities
- **Code Review**: Track pending code changes with diff viewer showing syntax highlighting, interdiffs, and moved line detection
- **Document Review**: Review documents, graphics, and other assets alongside code
- **Discussion Tracking**: All discussions around product decisions are tracked and searchable
- **Repository Integration**: Supports Bazaar, ClearCase, CVS, Git, Mercurial, Perforce, Plastic, and Azure DevOps
- **Rich API**: Build custom features, review UIs, data analysis, and more using the extension framework
- **Team Collaboration**: Manage multiple teams, projects, and review requests
- **Review UIs**: Custom review interfaces tailored to your workflows
- **User Authentication**: LDAP/Active Directory sync, OAuth, and traditional authentication

### Review Board Features
- **Diff Viewer**: Advanced diff display with syntax highlighting for many programming languages
- **Moved Line Detection**: Highlights lines that were added, removed, or changed
- **Commenting**: Rich commenting system with threaded discussions
- **Change Requests**: Formal review request workflow with assignees and reviewers
- **Status Tracking**: Track review status (pending, submitted, discarded, published)
- **Email Notifications**: Get notified on review updates and changes
- **Search**: Powerful search across reviews, comments, and discussions
- **Dashboard**: View all pending reviews in one place

## Configuration

### Environment Variables

#### Database (Automatically configured by Cloudron)
- `CLOUDRON_POSTGRESQL_HOST`: PostgreSQL host
- `CLOUDRON_POSTGRESQL_PORT`: PostgreSQL port
- `CLOUDRON_POSTGRESQL_DATABASE`: Database name
- `CLOUDRON_POSTGRESQL_USERNAME`: Database username
- `CLOUDRON_POSTGRESQL_PASSWORD`: Database password

#### Django Configuration
- `SECRET_KEY`: Django secret key (auto-generated, change in production)
- `ALLOWED_HOSTS`: Allowed hosts (default: `*`)
- `REVIEWBOARD_SITE_ROOT`: Site root URL (auto-configured)

#### Admin User
- `ADMIN_USERNAME`: Username for admin account
- `ADMIN_EMAIL`: Email address for admin account
- `ADMIN_PASSWORD`: Password for admin account

### Ports
- **8080**: Main HTTP port (web interface and API)

### Addons
- **PostgreSQL**: Required for database storage
- **Localstorage**: Used for media uploads and data

## Usage

### 1. Set Up Repositories

Via Web Interface:
1. Open Review Board
2. Go to "Admin" → "Repositories"
3. Click "Add Repository"
4. Configure:
   - Repository type (Git, Mercurial, etc.)
   - Repository URL
   - Repository name
   - Mirror configuration (if needed)
5. Click "Save"

Via API:
```bash
curl -X POST http://localhost:8080/api/repositories/ \
  -H "Authorization: Token your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "scm_type": "git",
    "path": "https://github.com/myorg/myproject.git",
    "mirror_path": "/path/to/mirror"
  }'
```

### 2. Create Review Request

Via Web Interface:
1. Go to "All Review Requests"
2. Click "New Review Request"
3. Configure:
   - Repository to review
   - Base branch (e.g., main)
   - Tip branch (e.g., feature/new-feature)
   - Reviewers
   - Description
4. Click "Create"

Via Git Hook:
```bash
# In your Git repository, configure post-commit hook
.git/hooks/post-commit

#!/bin/bash
# Review Board URL
RB_URL="http://your-app.cloudron.app"

# Create review request on commit
curl -X POST "$RB_URL/api/review-requests/" \
  -H "Authorization: Token your-api-token" \
  -H "Content-Type: application/json" \
  -d "{
    \"repository\": \"your-repo\",
    \"commit_id\": \"$(git rev-parse HEAD)\",
    \"branch\": \"$(git rev-parse --abbrev-ref HEAD)\",
    \"description\": \"Automated review request\"
  }"
```

### 3. Review Code Changes

Via Web Interface:
1. Open review request
2. View diff with syntax highlighting
3. Click lines to add comments
4. Use "Reply" for threaded discussions
5. Click "Ship It!" to approve changes
6. Or click "Discard" to reject

### 4. Use Power Pack (Extension)

Power Pack adds:
- **Report Generation**: Create formatted reports of reviews
- **PDF and Office Document Review**: Review PDF and Office files
- **Better Multi-Server Scalability**: Handle more concurrent users
- **GitHub Enterprise Integration**: Direct connection to GitHub Enterprise
- **LDAP/Active Directory User Sync**: Sync users from directory services

To enable Power Pack:
1. Get trial license from RBCommons
2. Install license via Admin panel
3. Restart Review Board

### 5. Configure Teams and Projects

**Create Team:**
1. Go to "Admin" → "Teams"
2. Click "Add Team"
3. Configure team name and description
4. Add users to team

**Create Project:**
1. Go to "Admin" → "Projects"
2. Click "Add Project"
3. Configure project settings
4. Assign repository to project
5. Assign team to project

### 6. Set Up Email Notifications

1. Go to "My Account" → "Email Settings"
2. Configure SMTP settings
3. Set notification preferences
4. Test email configuration

## Integration Examples

### GitHub Integration
```python
# Using Review Board Python API
from reviewboardapi import ReviewBoardAdmin

rb = ReviewBoardAdmin('http://your-app.cloudron.app', username='admin', password='password')

# Create review request for GitHub PR
review_request = rb.repositories.create(
    name='my-repo',
    scm_type='git',
    path='https://github.com/myorg/myproject.git'
)

request = rb.review_requests.create(
    repository=review_request,
    branch='feature/new-feature',
    commit_id='abc123def456',
    description='Automated review from GitHub'
)
```

### GitLab Integration
```bash
# GitLab CI job to create Review Board requests
curl -X POST http://localhost:8080/api/review-requests/ \
  -H "Authorization: Token $RB_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"repository\": \"$CI_PROJECT_PATH\",
    \"commit_id\": \"$CI_COMMIT_SHA\",
    \"branch\": \"$CI_COMMIT_REF_NAME\",
    \"description\": \"Review request from GitLab CI\"
  }"
```

### Mercurial Integration
```bash
# Mercurial hook for Review Board
.hg/hgrc

[hooks]
changegroup.post-reviewboard = python:/path/to/hg_reviewboard.py
```

### Perforce Integration
```bash
# Perforce trigger for Review Board
p4 change -o $CL | grep -q "^Change:" || exit

# Submit to Review Board on changelist submit
curl -X POST http://localhost:8080/api/review-requests/ \
  -H "Authorization: Token $RB_TOKEN" \
  -d @-
```

## Security

### Change Default Secret Key
The default secret key is auto-generated. **Change SECRET_KEY in production**:
```bash
# Generate new secret key
python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

# Set SECRET_KEY environment variable
```

### Use LDAP/Active Directory
Configure LDAP for centralized authentication:
```bash
LDAP_SERVER=ldap://your-ldap-server.com
LDAP_BASE_DN=dc=example,dc=com
LDAP_UID=uid
LDAP_DN_TEMPLATE=uid=%(user)s,ou=users,dc=example,dc=com
LDAP_BIND_DN=cn=admin,dc=example,dc=com
LDAP_BIND_PASSWORD=your-ldap-password
```

### API Token Management
1. Create API tokens in Review Board admin panel
2. Assign tokens to users or services
3. Use tokens in API requests
4. Regularly rotate tokens for security

### Repository Access Control
Configure which users can access which repositories:
1. Go to "Admin" → "Repositories"
2. Edit repository settings
3. Configure access permissions
4. Use team-based access control

## Troubleshooting

### Review Requests Not Showing
1. Check repository mirror is up to date
2. Verify webhook configuration
3. Check Review Board logs: `docker logs <container>`
4. Test API connectivity

### Database Connection Errors
1. Verify PostgreSQL addon is active
2. Check database credentials in Cloudron environment
3. Review database configuration
4. Ensure PostgreSQL is running

### Performance Issues
1. Increase memory limit in Cloudron settings
2. Enable memcached for caching
3. Optimize repository mirror settings
4. Review database query performance

### Email Notifications Not Working
1. Verify SMTP configuration
2. Check email queue in admin panel
3. Test email settings
4. Review mail server logs

## Architecture

```
                    ┌─────────────┐
                    │  Developer   │
                    │  (Git)       │
                    └──────┬──────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ Review Board │
                    │  (Django)    │
                    │  Dashboard    │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
       ┌──────────┐  ┌──────────┐  ┌──────────┐
       │ PostgreSQL│  │ Repository│  │ Email    │
       │ (Database)│  │  Mirror  │  │ Service  │
       └──────────┘  └──────────┘  └──────────┘
```

## Documentation

For more information on using Review Board:
- [Official Website](https://www.reviewboard.org/)
- [User Manual](https://www.reviewboard.org/docs/manual/latest/users/)
- [Admin Manual](https://www.reviewboard.org/docs/manual/latest/admin/)
- [API Documentation](https://www.reviewboard.org/docs/manual/latest/webapi/2.0/)
- [Power Pack](https://www.reviewboard.org/power-pack/)
- [GitHub Repository](https://github.com/reviewboard/reviewboard)
- [Docker Images](https://hub.docker.com/r/reviewboard/reviewboard)

## Support

For issues and questions:
- [GitHub Issues](https://github.com/reviewboard/reviewboard/issues)
- [Community Forum](https://www.reviewboard.org/)
- [Mailing Lists](https://www.reviewboard.org/mailing-lists/)
- [Commercial Support](https://rbcommons.com/support)

## Upstream

[GitHub Repository](https://github.com/reviewboard/reviewboard)
[Official Website](https://www.reviewboard.org/)