mirror of https://github.com/Shik3i/KoalaSync.git synced 2026-07-26 20:18:14 +00:00

Files

T

MacBook 5157428e74 docs: comprehensive repository polish + step-by-step user guide

Documentation Rewrites:
- AI_INIT.md: fix duplicate section numbers, add file responsibility map,
  fix stale manual mirror instruction, add room ID constraint
- PRIVACY.md: add TL;DR statement, data retention table, explicit
  <all_urls> justification, self-hosted instance disclaimer
- CONTRIBUTING.md: add local testing guide, version warning, room ID
  constraint, bug report requirements
- shared/README.md: complete event table (all 15 events), fix stale
  manifest.json reference
- docs/SYNC_GUIDE.md: Chrome→Browser, add README.md to sync list,
  drop stale RC5 reference
- server/README.md: sync env defaults with .env.example (1000/50)

New Documentation:
- docs/HOW_IT_WORKS.md: 10-step walkthrough covering room creation,
  invitation bridge flow, synchronized playback, force sync protocol,
  heartbeat system, and episode auto-sync. Includes exact data payloads.

Infrastructure Cleanup:
- docker-compose.yml: remove deprecated version key
- .dockerignore: remove dead .bat/.sh patterns
- README.md: add self-hosting extension config tip, link HOW_IT_WORKS

2026-05-04 05:41:43 +02:00

2.9 KiB

Raw Blame History

Contributing to KoalaSync

Thank you for your interest in contributing to KoalaSync! We welcome all contributions, from bug reports to new features.

Development Workflow

1. Prerequisites

Node.js (v18+)
Docker (for local server testing)

2. Setup

Clone the repository.
Run npm install in the root directory to install build dependencies.
Run the build script to synchronize protocol constants and generate browser bundles:
```
node scripts/build-extension.js
```

3. Testing Locally

Load dist/chrome/ as an "Unpacked Extension" in Chrome (chrome://extensions/ → Developer Mode → Load Unpacked).
For Firefox, load dist/firefox/ via about:debugging → "Load Temporary Add-on".
Start the relay server: docker-compose up --build.
Use two different browser profiles (or Chrome + Firefox) to test multi-peer synchronization.
Use the extension's Dev tab to verify real-time video element metadata (readyState, currentTime, paused).

4. Protocol Synchronization

KoalaSync uses a "Single Source of Truth" for protocol constants in shared/constants.js.

CRITICAL: If you modify the constants, you MUST run the build script:
```
node scripts/build-extension.js
```
This will automatically synchronize the changes to the extension and generate the browser-specific bundles in the dist/ folder.

5. Code Standards

Vanilla JS: The extension must remain dependency-free. Do not add npm packages to the extension/ directory.
Privacy: Do not add external requests (CDNs, fonts, analytics, etc.).
Comments: Maintain the existing documentation style, especially for complex sync logic.
Room IDs: Room IDs are restricted to [a-zA-Z0-9-] (alphanumeric + hyphens only). Ensure any UI that generates room IDs follows this constraint.

6. Version Numbers

Important

Do NOT manually bump version numbers. The CI pipeline automatically injects the version from the git tag into manifest.base.json, shared/constants.js, and package.json during release builds. Manually changing version numbers in a PR will cause conflicts.

Pull Request Process

Create a new branch for your feature or bugfix.
Ensure your code is tested locally (Chrome and Firefox).
Update relevant documentation (e.g., docs/ARCHITECTURE.md if you change the protocol).
Submit your PR with a clear description of the changes.

Bug Reports

When reporting a bug, please include:

Browser: Chrome / Firefox / Edge + version number.
Extension Version: Visible in the popup's Dev tab.
Dev Tab Output: Copy the connection status, logs, and video debug info from the Dev tab.
Steps to Reproduce: A clear sequence of actions that triggers the issue.

Security

If you find a security vulnerability, please do not open a public issue. Instead, refer to our SECURITY.md for responsible disclosure instructions.

2.9 KiB Raw Blame History