Contributing to RClone Manager

Thank you for your interest in contributing to RClone Manager! We appreciate contributions of all kinds — from bug reports and feature requests to code improvements and documentation updates.

📋 Table of Contents

Code of Conduct
How Can I Contribute?
Development Setup
- Prerequisites
- Setting Up the Project
Project Structure
Development Workflow
Submitting Changes
- Pull Request Process
- PR Guidelines
Additional Resources

Code of Conduct

We are committed to providing a welcoming and inspiring community for all. Please be respectful and constructive in your interactions with other contributors.

How Can I Contribute?

Reporting Bugs

If you find a bug, please open a bug report with the following information:

Description: A clear and concise description of the bug
Steps to Reproduce: Detailed steps to reproduce the issue
Expected Behavior: What you expected to happen
Actual Behavior: What actually happened
Environment: OS, version, and any other relevant details
Screenshots/Logs: If applicable, add screenshots or error logs

Suggesting Features

We love new ideas! To suggest a feature, please open a feature request including:

Description: A clear description of the feature
Use Case: Why this feature would be useful
Alternatives: Any alternative solutions you've considered
Additional Context: Mockups, examples, or references

Contributing Code

Before starting work on a significant change:

Check existing issues — See if someone is already working on it
Open a discussion — For major changes, open an issue to discuss your approach first
Fork the repository — Create your own fork to work on
Create a branch — Use a descriptive branch name (e.g., feat/new-feature or fix/bug-name)

Improving Documentation

Documentation improvements are always welcome! This includes:

Fixing typos or clarifying existing docs
Adding examples or tutorials
Updating the Wiki
Improving code comments

Adding Translations

We use BCP-47 language tags (e.g., en-US, tr-TR, de-DE) for internationalization.

Important

We use Crowdin for translations. Please contribute translations here: https://crowdin.com/project/rclone-manger You can still submit fixes via Pull Requests if you prefer.

Steps to Add a New Language

Create the translation directory:
```
mkdir -p resources/i18n/YOUR-LANG
```

Copy base translation files:

cp -r resources/i18n/en-US/* resources/i18n/YOUR-LANG/

Update the backend schema (src-tauri/src/core/settings/schema.rs):

Add your language to SUPPORTED_LANGUAGES and the language options:

// Add your BCP-47 code here
const SUPPORTED_LANGUAGES: &[&str] = &["en-US", "tr-TR", "de-DE"];

// Add your language option (use native language name)
options(
    ("en-US", "English (US)"),
    ("tr-TR", "Türkçe (Türkiye)"),
    ("de-DE", "Deutsch (Deutschland)")  // ← New language
)

Translate the JSON files:

Translate all string values in the files under resources/i18n/YOUR-LANG/.
- main.json: General UI strings.
- rclone.json: Rclone flag names and help texts.
Keep the JSON keys unchanged.
Test your translation:
```
npm run tauri dev
```
Then change the language in Settings → General → Language.

Translation Guidelines

Use native language names for the language selector (e.g., "Deutsch" not "German")
Keep placeholders intact — Don't translate {{variable}} placeholders
Maintain JSON structure — Only translate string values, not keys
Test special characters — Ensure UTF-8 encoding works correctly
Use formal/informal consistently — Choose one register and stick to it

README Translation (Optional but Appreciated!)

If you'd like to go the extra mile, you can also translate the README:

Copy README.md to README.YOUR-LANG.md (e.g., README.de-DE.md)
Translate the content (keep badges and links working)

Add your language to the language selector at the top of all README files:

<p align="center">
  <a href="README.md">English</a> • <a href="README.tr-TR.md">Türkçe</a> •
  <a href="README.de-DE.md">Deutsch</a>
  <!-- New -->
</p>

BCP-47 Language Codes

Common language codes:

Code	Language
`en-US`	English (US)
`tr-TR`	Turkish (Turkey)
`de-DE`	German (Germany)
`fr-FR`	French (France)
`zh-CN`	Chinese (Simplified)

Cron Expressions

The application uses cronstrue to display human-readable cron schedules. To support a new language:

Register the Locale: Import the locale in src/app/core/i18n/cron-locale.mapper.ts.
```
import 'cronstrue/locales/fr'; // Example for French
```
Verify Mapping: Ensure getCronstrueLocale correctly maps your app locale (e.g., fr-FR) to the cronstrue locale (e.g., fr).

Managing Rclone Flags

The Rclone flags (options) are stored in resources/i18n/{lang}/rclone.json. These are used to provide translated titles and help text for Rclone's various options.

Updating Flag Definitions

To update the flag definitions from a running Rclone instance:

Start the app in dev mode:
```
npm run tauri dev
```
Find the RC port: Check the console logs or ps aux | grep rclone for the --rc-addr port (e.g., 51900).

Fetch new definitions:

curl -X POST http://127.0.0.1:PORT/options/info -d "{}" -o flags.json

Process and Update: Extract the Name and Help fields and update the rclone.json files. Maintain the flat structure:

{
  "options": {
    "flag_name": {
      "title": "Title",
      "help": "Description"
    }
  }
}

Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Required

Node.js (v18 or higher) and npm
Rust (latest stable version via rustup)
Rclone (for runtime functionality)

Platform-Specific Requirements

Linux: Standard build tools (build-essential on Debian/Ubuntu)
macOS: Xcode Command Line Tools
Windows: Visual Studio Build Tools or MSVC

For detailed platform-specific prerequisites, see the Building Wiki.

Setting Up the Project

Clone your fork:

git clone https://github.com/YOUR_USERNAME/rclone-manager.git
cd rclone-manager

Install dependencies:
```
npm install
```
Run in development mode:
```
npm run tauri dev
```
Run headless mode (development) (optional):
```
npm run headless-dev
```
Run headless mode (production) (optional):
```
npm run headless
```

Project Structure

rclone-manager/
├── .github/           # GitHub workflows and configurations
├── src/               # Angular frontend source code
│   ├── app/          # Application components, services, and modules
│   ├── assets/       # Static assets (images, icons)
│   └── styles/       # Global styles and themes
├── src-tauri/         # Rust backend (Tauri)
│   ├── src/          # Rust source code
│   │   ├── core/     # Core backend logic
│   │   ├── server/   # Web server implementation (headless mode)
│   │   ├── rclone/   # Rclone backend logic
│   │   └── utils/    # Utility functions
│   └── tauri.conf.json # Tauri configuration
│   └── tauri.conf.headless.json # Tauri configuration (headless mode)
│   └── Cargo.toml    # Rust dependencies and configuration
├── headless/          # Headless/web server mode documentation
└── package.json       # Node.js dependencies and scripts

Key Directories

src/app/: Angular components, services, and application logic
src-tauri/src/core/: Core Rust backend logic (scheduler, settings, security)
src-tauri/src/server/: Web server implementation for headless mode
src-tauri/src/rclone/: Rclone backend logic
.github/workflows/: CI/CD workflows for building and releasing

Development Workflow

Working on Features

Create a feature branch:
```
git checkout -b feat/your-feature-name
```
Make your changes in the appropriate directory:
- Frontend changes → src/
- Backend changes → src-tauri/src/
- Documentation → README.md, Wiki, or *.md files
Test your changes:
```
npm run tauri dev
```
Commit your changes with clear, descriptive messages:
```
git commit -m "feat: add new feature description"
```

Code Style

We use automated linting and formatting to maintain code quality. All code must pass linting checks before being merged.

Frontend (TypeScript/Angular)

Linting: ESLint with Angular-specific rules
Formatting: Prettier

# Run linter
npm run lint

# Fix linting issues automatically
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

Backend (Rust)

Linting: Clippy
Formatting: rustfmt

# Run Rust linter
npm run lint:rust

# Format Rust code
npm run format:rust

# Check Rust formatting
npm run format:rust:check

Run All Checks

# Check everything
npm run lint:all

# Fix everything automatically
npm run fix:all

Note: We use Husky and lint-staged to automatically lint and format code on commit. See LINTING.md for detailed information.

Testing

Currently, the project uses manual testing. We welcome contributions to add automated tests!

Manual Testing Checklist:

Test on your target platform (Linux/macOS/Windows)
Verify the feature works as expected
Check for console errors or warnings
Test edge cases and error handling
Ensure UI remains responsive

Submitting Changes

Pull Request Process

Ensure your code passes all checks:
```
npm run lint:all
```
Push your branch to your fork:
```
git push origin feat/your-feature-name
```
Open a Pull Request against the main branch of the original repository
Fill out the PR template with:
- Description of changes
- Related issue(s)
- Testing performed
- Screenshots (if UI changes)
Wait for review — Maintainers will review your PR and may request changes
Address feedback — Make requested changes and push updates
Merge — Once approved, a maintainer will merge your PR

PR Guidelines

Good PR Practices

✅ Keep PRs focused — One feature or bug fix per PR
✅ Write clear commit messages — Use Conventional Commits format:
- feat: for new features
- fix: for bug fixes
- docs: for documentation
- refactor: for code refactoring
- style: for formatting changes
- chore: for maintenance tasks
✅ Update documentation — If your PR changes behavior, update relevant docs
✅ Test thoroughly — Ensure your changes work on your platform
✅ Include screenshots — For UI changes, include before/after screenshots

What to Avoid

❌ Large PRs with multiple unrelated changes
❌ Committing generated files (node_modules/, dist/, etc.)
❌ Breaking existing functionality without discussion
❌ Incomplete or untested features

Additional Resources

Documentation

Wiki — Building instructions, installation guides, and more
LINTING.md — Detailed linting and formatting guide
ISSUES.md — Known issues and workarounds
CHANGELOG.md — Version history and changes

Communication

GitHub Issues — Bug reports and feature requests
GitHub Discussions — General questions and ideas
Project Board — Development roadmap and progress

Learning Resources

Tauri Documentation — Tauri framework docs
Angular Documentation — Angular framework docs
Rclone Documentation — Rclone tool documentation
Rust Book — Learning Rust
TypeScript Handbook — Learning TypeScript

🙏 Thank You

Your contributions make RClone Manager better for everyone. We appreciate your time and effort!

Made with ❤️ by the Zarestia Dev Team and contributors
_{Licensed under GNU GPLv3}

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History