From f90a83ef1e6a6329b7ae7ea43a723b3278e25a60 Mon Sep 17 00:00:00 2001 From: vorotamoroz Date: Fri, 19 Jun 2026 11:33:38 +0100 Subject: [PATCH] Update docs --- CONTRIBUTING.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++ devs.md | 20 ++++++++++++++ docs/settings.md | 7 ++--- 3 files changed, 94 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..487bc4f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,70 @@ +# Contributing to Self-hosted LiveSync + +Thank you for your interest in contributing to Self-hosted LiveSync! We welcome all contributions, including bug reports, feature requests, documentation improvements, translations, and pull requests. + +## Getting Started + +To set up the development environment, please follow these steps: + +1. Clone the repository recursively to ensure all Git submodules are loaded: + ```bash + git clone --recursive https://github.com/vrtmrz/obsidian-livesync + ``` + If you have already cloned the repository without submodules, run the following command: + ```bash + git submodule update --init --recursive + ``` + +2. Install the package dependencies: + ```bash + npm ci + ``` + +3. Build the plug-in: + ```bash + npm run build + ``` + +For a more comprehensive guide on development workflows, testing configurations, and subrepos, please refer to [devs.md](devs.md). + +## Guidelines for Contributions + +### 1. Code Style and Verification + +Before submitting a pull request, you must run verification scripts locally to ensure that there are no syntax, type, or linting errors: + +- Run type checking and linting: + ```bash + npm run check + ``` +- Run unit tests: + ```bash + npm run test:unit + ``` + +If you have the capability and a suitable environment (such as Linux and Docker), running the CLI End-to-End (E2E) tests is also highly appreciated. Instructions are detailed in [devs.md](devs.md). If you cannot run E2E tests locally, please explicitly ask to run the tests on the CI by stating 'Please run CI tests' in your pull request description. + +### 2. Documentation and UI Text Style + +To maintain consistency across the project, we ask that you follow the established writing style and conventions of the codebase when contributing documentation or user-facing messages: + +- **Spelling**: Prioritise region-independent, neutral spelling if a suitable word exists. If there is no such word, please use British English spelling to align with the codebase's style (for example: preferring '-ise' and '-isation' suffixes over '-ize' and '-ization'). However, we do not treat alternative spellings as errors. +- **Oxford Comma**: Use the serial (Oxford) comma to separate items in lists of three or more (for example: 'settings, snippets, and themes'). +- **Logical Punctuation**: Place punctuation marks outside quotation marks unless they are part of the quoted text itself (for example: write 'dialogue', not 'dialogue,'). +- **No Contractions**: Avoid using contractions in general text or documentation (for example: write "do not" instead of "don't", and "cannot" instead of "can't"). +- **Affirmative Phrasing**: Avoid asking questions using negative forms in user-facing dialogue. Use affirmative questions to prevent translation and interpretation discrepancies. +- **Specific Words**: Use 'dialogue' for documentation and user-facing messages (use 'dialog' only inside source code). Use the hyphenated form 'plug-in' in user-facing text (use 'plugin' only in configuration settings or technical contexts). + +For a detailed list of vocabulary conventions and terms, please refer to [docs/terms.md](docs/terms.md). + +### 3. Translations + +To add or update translations, please refer to [docs/adding_translations.md](docs/adding_translations.md) for detailed instructions. + +### 4. Git Submodules + +The `src/lib` directory is a Git submodule pointing to the shared library `livesync-commonlib`. If you wish to propose changes to the shared library, do not modify `src/lib` directly. Instead, please submit a separate pull request to the [livesync-commonlib repository](https://github.com/vrtmrz/livesync-commonlib). + +## License + +By contributing, you agree that your contributions will be licensed under the MIT License. diff --git a/devs.md b/devs.md index 8a3cad6..279dbfb 100644 --- a/devs.md +++ b/devs.md @@ -76,6 +76,26 @@ To facilitate development and testing, the build process can automatically copy - `test/unit/` - Unit tests (via vitest, as harness is browser-based) - `test/harness/` - Mock implementations (e.g., `obsidian-mock.ts`) +### Import Path Normalisation + +The codebase uses `@/` and `@lib/` path aliases to keep import structures clean. To normalise imports and exports across files, use the following utility script: +```bash +npm run pretty:importpath +``` +Under the hood, this runs Deno with the script [utilsdeno/normalise-imports.ts](file:///p:/plant25/obsidian/projects/obsidian-livesync/utilsdeno/normalise-imports.ts). You can pass additional flags to this script if required (by running it via Deno directly from the `utilsdeno` directory): +- `--run`: Applies the changes (the script runs in dry-run mode by default). +- `--all-alias`: Normalises sibling/child relative imports starting with `./` to use aliases. + +### Type Generation + +To generate fallback type definitions for the shared library and add appropriate Deno ignore comments (which suppresses Deno compilation warnings and linting warnings inside the `_types` directory), run: +```bash +npm run build:lib:types +``` +This script executes: +1. TypeScript compilation (`tsconfig.types.json`) to output definitions to the `_types` directory. +2. The Deno script [utilsdeno/types-add-ignore.ts](file:///p:/plant25/obsidian/projects/obsidian-livesync/utilsdeno/types-add-ignore.ts) to prepend Deno ignore comments to the generated type files. + ## Architecture diff --git a/docs/settings.md b/docs/settings.md index 3727346..32c3e91 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -515,7 +515,7 @@ Saving will be performed forcefully after this number of seconds. #### Use the trash bin Setting key: trashInsteadDelete -Move remotely deleted files to the trash, instead of deleting. +Move remotely deleted files to the trash, instead of deleting. On Obsidian v1.7.2 or newer, file deletion respects the user's deletion preferences (by utilising the `FileManager.trashFile` API), regardless of this setting. #### Keep empty folder @@ -557,10 +557,11 @@ Setting key: notifyAllSettingSyncFile ### 7. Hidden Files (Advanced) -#### Hidden file synchronisation - #### Enable Hidden files sync +Setting key: syncInternalFiles +Enable the synchronisation of hidden files and folders (e.g. settings files, templates, snippets, and themes under `.obsidian`). + #### Scan for hidden files before replication Setting key: syncInternalFilesBeforeReplication