# 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](#code-of-conduct)
- [How Can I Contribute?](#how-can-i-contribute)
- [Reporting Bugs](#reporting-bugs)
- [Suggesting Features](#suggesting-features)
- [Contributing Code](#contributing-code)
- [Improving Documentation](#improving-documentation)
- [Adding Translations](#adding-translations)
- [Development Setup](#development-setup)
- [Prerequisites](#prerequisites)
- [Setting Up the Project](#setting-up-the-project)
- [Project Structure](#project-structure)
- [Development Workflow](#development-workflow)
- [Working on Features](#working-on-features)
- [Code Style](#code-style)
- [Testing](#testing)
- [Submitting Changes](#submitting-changes)
- [Pull Request Process](#pull-request-process)
- [PR Guidelines](#pr-guidelines)
- [Additional Resources](#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](https://github.com/Zarestia-Dev/rclone-manager/issues/new?template=bug_report.md) 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](https://github.com/Zarestia-Dev/rclone-manager/issues/new?template=feature_request.md) 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:
1. **Check existing issues** β See if someone is already working on it
2. **Open a discussion** β For major changes, open an issue to discuss your approach first
3. **Fork the repository** β Create your own fork to work on
4. **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](https://hakanismail.info/zarestia/rclone-manager/docs)
- 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
1. **Create the translation directory**:
```bash
mkdir -p resources/i18n/YOUR-LANG
```
2. **Copy base translation files**:
```bash
cp -r resources/i18n/en-US/* resources/i18n/YOUR-LANG/
```
3. **Update the backend schema** (`backend/core/src/services/settings/schema.rs`):
Add your language to `SUPPORTED_LANGUAGES` and the language options:
```rust
// 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
)
```
4. **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.
- `rclone-providers.json`: Rclone provider configuration options.
Keep the JSON keys unchanged.
5. **Portable Edition Readme Files (Important)**:
When adding support for a new language, please also create the language-specific portable README text files under `resources/portable/`:
- `README_YOUR-LANG.txt` (e.g., `resources/portable/README_pt-BR.txt`)
- `README_linux_YOUR-LANG.txt` (e.g., `resources/portable/README_linux_pt-BR.txt`)
You can copy `README_en-US.txt` and `README_linux_en-US.txt` as templates and translate their content into your target language.
6. **Android Native Strings (Mobile)**:
When translating native Android components (such as foreground services, SAF notifications, and channel descriptions), add or update the language `strings.xml` file under `backend/desktop/gen/android/app/src/main/res/values-YOUR-LANG/strings.xml` (e.g., `values-tr`, `values-es`, `values-fr`, `values-ja`, `values-pt-rBR`, `values-ru`, `values-uk`, `values-zh-rCN`).
Example (`values-tr/strings.xml`):
```xml
English β’ TΓΌrkΓ§e β’ Deutsch
``` #### 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) | | `pt-BR` | Portuguese (Brazil) | | `zh-CN` | Chinese (Simplified) | | `zh-TW` | Chinese (Traditional) | ### Cron Expressions The application uses `cronstrue` to display human-readable cron schedules. To minimize initial bundle size, cron locales are dynamically loaded on demand: 1. **Register the Dynamic Import**: Add the locale import case to `ensureCronLocaleLoaded` in `src/app/services/i18n/cron-locale.mapper.ts`: ```typescript case 'fr': await import('cronstrue/locales/fr'); break; ``` 2. **Verify Mapping**: Ensure `getCronstrueLocale` in `src/app/services/i18n/cron-locale.mapper.ts` correctly maps your app locale (e.g., `fr-FR`) to the `cronstrue` locale (e.g., `fr`). --- ### Managing Rclone Flags & Providers The Rclone flag and provider definitions are stored in: - `resources/i18n/{lang}/rclone.json` (rclone global flags) - `resources/i18n/{lang}/rclone-providers.json` (rclone provider configuration options) These files provide translated titles and help text for Rclone options across all supported languages. #### Updating Flag & Provider Definitions Instead of manually fetching and editing definitions, use the built-in sync scripts: 1. **Start `rclone rcd` on Port `5572`** (or launch `npm run dev:headless` / `npm run tauri dev`). ```bash rclone rcd --rc-no-auth --rc-addr :5572 ``` 2. **Sync Flag Definitions**: ```bash npm run sync:flags ``` This fetches option info from rclone and appends missing flag keys to `resources/i18n/*/rclone.json`. To read definitions from the installed rclone without starting an RC server: ```bash npm run sync:flags -- --loopback ``` If rclone cannot provide its schema, the command exits without changing translation files. 3. **Sync Provider Definitions**: ```bash npm run sync:providers ``` This fetches provider configuration schemas from rclone and appends missing options to `resources/i18n/*/rclone-providers.json`. 4. **Translate New Keys**: Newly added keys in non-English translation files will be tagged with `"TODO": "NEEDS_TRANSLATION"`. Translate the `title` and `help` values into the target language and remove the `"TODO"` marker. 5. **Pruning Obsolete Keys (Optional)**: `--prune` removes keys absent from the selected rclone schema and the app's static flag definitions. Runtime mount/serve type translations are retained. Absence from one version or platform does not prove a key is obsolete for every supported build. Preview the exact removal candidates first. `--dry-run` does not write files: ```bash npm run sync:flags -- --loopback --prune --dry-run npm run sync:providers -- --loopback --prune --dry-run ``` After reviewing the candidates against the versions and platforms you support, omit `--dry-run` to apply the changes. Pruning rejects malformed responses and schemas missing core blocks or providers; these checks cannot detect every possible partial schema. --- ## 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](https://rustup.rs/)) - **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](https://hakanismail.info/zarestia/rclone-manager/docs/building). ### Setting Up the Project 1. **Clone your fork**: ```bash git clone https://github.com/YOUR_USERNAME/rclone-manager.git cd rclone-manager ``` 2. **Install dependencies**: ```bash npm install ``` 3. **Run in development mode**: ```bash npm run tauri dev ``` 4. **Run headless mode (development)** (optional): ```bash npm run headless-dev ``` 5. **Run headless mode (production)** (optional): ```bash 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 βββ backend/ # Rust workspace β βββ core/ # Shared services and command contract β βββ server/ # Tokio/Axum server, deployment docs and Linux service template β βββ desktop/ # Tauri, desktop/mobile integrations and packaging β βββ Cargo.toml # Workspace configuration β βββ Cargo.lock # Shared dependency lockfile βββ package.json # Node.js dependencies and scripts ``` ### Key Directories - **`src/app/`**: Angular components, services, and application logic - **`backend/core/src/services/`**: Core Rust backend logic (scheduler, settings, security) - **`backend/`**: Shared core, independent HTTP server, and native Tauri application; see [backend architecture](backend/ARCHITECTURE.md) - **`backend/core/src/rclone/`**: Rclone backend logic - **`.github/workflows/`**: CI/CD workflows for building and releasing --- ## Development Workflow ### Working on Features 1. **Create a feature branch**: ```bash git checkout -b feat/your-feature-name ``` 2. **Make your changes** in the appropriate directory: - Frontend changes β `src/` - Backend changes β `backend/core/src/`, `backend/server/src/`, or `backend/desktop/src/` - Documentation β `README.md`, Wiki, or `*.md` files 3. **Test your changes**: ```bash npm run tauri dev ``` 4. **Commit your changes** with clear, descriptive messages: ```bash 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/SCSS/JSON) - **Linting**: ESLint with Angular-specific rules - **Formatting**: Prettier ```bash # Run ESLint and Clippy npm run lint # Format code with Prettier (TS, HTML, SCSS, JSON) & Cargo fmt npm run format # Or run Prettier directly: npx prettier --check "**/*.{ts,html,scss,json}" npx prettier --write "**/*.{ts,html,scss,json}" ``` #### Backend (Rust) - **Linting**: Clippy (`cd backend/desktop && cargo clippy -- -D warnings`) - **Formatting**: rustfmt (`cargo fmt --manifest-path backend/Cargo.toml --all`) #### Run All Checks & Fixes ```bash # Fix SVG IDs, Prettier formatting, and ESLint issues automatically npm run fix:all # Audit i18n translation keys npm run audit:i18n ``` **Note**: We use [Husky](https://typicode.github.io/husky/) and [lint-staged](https://github.com/okonet/lint-staged) to automatically lint and format code on commit. See [LINTING.md](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 1. **Ensure your code passes all checks**: ```bash npm run lint:all ``` 2. **Push your branch to your fork**: ```bash git push origin feat/your-feature-name ``` 3. **Open a Pull Request** against the `main` branch of the original repository 4. **Fill out the PR template** with: - Description of changes - Related issue(s) - Testing performed - Screenshots (if UI changes) 5. **Wait for review** β Maintainers will review your PR and may request changes 6. **Address feedback** β Make requested changes and push updates 7. **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](https://www.conventionalcommits.org/) 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](https://hakanismail.info/zarestia/rclone-manager/docs)** β Building instructions, installation guides, and more - **[LINTING.md](LINTING.md)** β Detailed linting and formatting guide - **[ISSUES.md](ISSUES.md)** β Known issues and workarounds - **[CHANGELOG.md](CHANGELOG.md)** β Version history and changes ### Communication - **[GitHub Issues](https://github.com/Zarestia-Dev/rclone-manager/issues)** β Bug reports and feature requests - **[GitHub Discussions](https://github.com/Zarestia-Dev/rclone-manager/discussions)** β General questions and ideas - **[Project Board](https://github.com/users/Zarestia-Dev/projects/2)** β Development roadmap and progress ### Learning Resources - **[Tauri Documentation](https://tauri.app/)** β Tauri framework docs - **[Angular Documentation](https://angular.io/)** β Angular framework docs - **[Rclone Documentation](https://rclone.org/)** β Rclone tool documentation - **[Rust Book](https://doc.rust-lang.org/book/)** β Learning Rust - **[TypeScript Handbook](https://www.typescriptlang.org/docs/)** β 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