Contributing - r2Vault

Welcome Contributors!

Thank you for your interest in contributing to r2Vault! This guide will help you get started with the development workflow, code style, and submission process.

r2Vault is an open-source macOS client for Cloudflare R2, built with Swift 6 and SwiftUI.

How to Contribute

There are many ways to contribute to r2Vault:

Report bugs via GitHub Issues
Suggest features or improvements
Fix bugs and submit pull requests
Add new features that enhance the user experience
Improve documentation and code comments
Write tests to increase code coverage

Development Workflow

Fork and clone

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/YOUR-USERNAME/r2Vault.git
cd r2Vault

Create a branch

Create a feature branch for your changes:

git checkout -b feature/your-feature-name

Use descriptive branch names:

feature/add-bucket-search
fix/upload-progress-bug
docs/update-readme

Make your changes

Open Fiaxe.xcodeproj in Xcode
Make your changes following the code style guidelines
Test your changes thoroughly
Update documentation if needed

Commit your changes

Write clear, descriptive commit messages:

git add .
git commit -m "Add bucket search functionality"

Good commit messages:

Start with a verb (Add, Fix, Update, Remove)
Keep the subject line under 50 characters
Add details in the body if needed

Push and create a PR

Push your branch and open a pull request:

git push origin feature/your-feature-name

Then visit github.com/xaif/r2Vault to create your pull request.

Code Style

Swift 6 Standards

r2Vault follows Swift 6 conventions and leverages modern language features:

Strict concurrency enabled throughout the project
@Observable macro for reactive state management (no more @Published)
async/await for all asynchronous operations
TaskGroup for concurrent operations (uploads, deletions)
MainActor annotations where appropriate

SwiftUI Patterns

State Management:

@Observable
final class AppViewModel {
    var browserObjects: [R2Object] = []
    var uploadTasks: [FileUploadTask] = []
    // ...
}

View Injection:

.environment(viewModel)

Async Operations:

Task {
    await uploadPendingTasks()
}

Code Organization

Follow the existing project structure:

Fiaxe/
├── Models/          # Data models (R2Object, UploadTask, etc.)
├── Services/        # Business logic and API calls
├── ViewModels/      # Observable view models
└── Views/           # SwiftUI views

Naming Conventions:

Use descriptive names: uploadSingleFile not upload1
Follow Swift API design guidelines
Use camelCase for functions and variables
Use PascalCase for types and protocols

Comments:

Add comments for complex logic
Use // MARK: - to organize code sections
Document public APIs with doc comments

Project Structure

Core Components

Models

R2Credentials.swift — Bucket credential storage
R2Object.swift — File/folder object model
UploadItem.swift — Upload history item
UploadTask.swift — Upload task with progress tracking

Services

AWSV4Signer.swift — S3-compatible request signing with CryptoKit
KeychainService.swift — Secure credential persistence
MenuBarManager.swift — NSStatusItem + NSPopover management
R2BrowseService.swift — Bucket listing, delete, recursive operations
R2UploadService.swift — File upload with progress streaming
ThumbnailCache.swift — Memory + disk thumbnail cache
UpdateService.swift — GitHub release update checker
UploadHistoryStore.swift — Upload history persistence

ViewModels

AppViewModel.swift — Central application state using @Observable
- Browser navigation and state
- Upload queue management
- Credential management
- Update checking

Views

BrowserView.swift — Main file browser (icon/list views)
MenuBarView.swift — Menu bar popover UI
SettingsView.swift — Credentials and preferences
UploadQueueView.swift — Active uploads HUD
UploadHistoryView.swift — Past uploads list

Tech Stack

Layer	Technology
UI	SwiftUI
Architecture	MVVM with @Observable
Concurrency	Swift async/await, TaskGroup
Authentication	AWS Signature V4 (CryptoKit)
Networking	URLSession
Storage	UserDefaults, Keychain
Menu Bar	AppKit NSStatusItem + NSPopover

Testing

Manual Testing

Before submitting a PR, test these key flows:

File Upload
File Browser
File Management
Menu Bar

Drag and drop files from Finder
Upload via file picker button
Upload folders recursively
Cancel in-progress uploads
Verify progress tracking
Check public URL auto-copy

Test Environments

Development: Test with a non-production R2 bucket
Multiple buckets: Verify bucket switching works correctly
Large files: Test upload progress with files >100MB
Folders: Test recursive upload of nested folder structures

Always test with a development bucket. Never test deletions on production data.

Submitting Pull Requests

PR Checklist

Before submitting, ensure:

Code builds without warnings or errors
Changes have been manually tested
Code follows Swift 6 and SwiftUI patterns
No sensitive data (API keys, credentials) in code
Commit messages are clear and descriptive
PR description explains what and why

PR Description Template

## What
Brief description of the changes.

## Why
Why is this change needed? What problem does it solve?

## How
How does this implementation work?

## Testing
How did you test these changes?

## Screenshots (if applicable)
Add screenshots for UI changes.

Review Process

Submit PR: Create your pull request on GitHub
Automated checks: GitHub Actions will build your changes
Code review: Maintainers will review your code
Address feedback: Make requested changes if needed
Merge: Once approved, your PR will be merged

Areas for Contribution

High Priority

Testing

Add unit tests and UI tests to improve code coverage.

Performance

Optimize thumbnail caching and large file uploads.

Error Handling

Improve error messages and recovery flows.

Accessibility

Add VoiceOver support and keyboard navigation.

Feature Ideas

File preview: In-app preview for more file types
Batch operations: Bulk rename, move, copy
Search: Advanced search with filters
Sync: Two-way sync between local and R2
Sharing: Generate presigned URLs with expiration
Analytics: Storage usage and bandwidth tracking

Resources

GitHub Repository

View source code and submit issues

Building from Source

Build instructions and troubleshooting

Cloudflare R2 Docs

R2 API reference and documentation

Swift Docs

Swift language documentation

Questions?

If you have questions or need help:

Open a GitHub Discussion
File an Issue for bugs
Check existing issues and PRs for similar work

License

r2Vault is open source under the MIT License. By contributing, you agree that your contributions will be licensed under the same license.

Architecture

Services

Models

Building

​Welcome Contributors!

​How to Contribute

​Development Workflow

​Code Style

​Swift 6 Standards

​SwiftUI Patterns

​Code Organization

​Project Structure

​Core Components

​Tech Stack

​Testing

​Manual Testing

​Test Environments

​Submitting Pull Requests

​PR Checklist

​PR Description Template

​Review Process

​Areas for Contribution

​High Priority

Testing

Performance

Error Handling

Accessibility

​Feature Ideas

​Resources

GitHub Repository

Building from Source

Cloudflare R2 Docs

Swift Docs

​Questions?

​License

Welcome Contributors!

How to Contribute

Development Workflow

Code Style

Swift 6 Standards

SwiftUI Patterns

Code Organization

Project Structure

Core Components

Tech Stack

Testing

Manual Testing

Test Environments

Submitting Pull Requests

PR Checklist

PR Description Template

Review Process

Areas for Contribution

High Priority

Feature Ideas

Resources

Questions?

License