Skip to content

armgit / mimik

Public Imported from GitHub
0

🎬 A browser extension and desktop app that turns your clicks into step-by-step guides with annotated screenshots πŸ“–

docs: add CONTRIBUTING.md

Luis Ortiz57b47cc201af
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..1ce1d53
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,138 @@
+# Contributing to Mimik
+
+Thanks for your interest in contributing! Bug reports, feature requests, PRs, and translations are all welcome.
+
+## Licensing
+
+By submitting a pull request or any contribution to this repository, you agree that your contribution will be licensed under the [MIT License](./LICENSE).
+
+You represent that you have the right to submit the contribution and that it does not infringe any third-party rights.
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 22+
+- [pnpm](https://pnpm.io) 10+
+- Chrome or Firefox (for testing)
+
+### Install
+
+```bash
+git clone https://github.com/westpoint-io/mimik.git
+cd mimik
+pnpm install
+```
+
+### Run in development
+
+```bash
+pnpm dev # Chrome (MV3) with HMR
+pnpm dev:firefox # Firefox (MV3) with HMR
+```
+
+WXT launches a fresh browser instance with the extension loaded.
+
+### Build
+
+```bash
+pnpm build # Chrome β†’ .output/chrome-mv3/
+pnpm build:firefox # Firefox β†’ .output/firefox-mv3/
+pnpm zip:all # package both browsers
+```
+
+### Test
+
+```bash
+pnpm test # run all tests once
+pnpm test:watch # watch mode
+pnpm test:cov # coverage report
+```
+
+### Lint & format
+
+```bash
+pnpm lint # check
+pnpm lint:fix # auto-fix
+pnpm format # format only
+```
+
+## Project Layout
+
+```
+src/
+β”œβ”€β”€ core/ # Business logic (no UI dependencies)
+β”‚ β”œβ”€β”€ capture/ # Recording pipeline (events, AI, DOM context)
+β”‚ β”œβ”€β”€ blur/ # Smart blur (regex presets, DOM scanner, panel)
+β”‚ β”œβ”€β”€ export/ # HTML, PDF, Markdown generators
+β”‚ β”œβ”€β”€ guideme/ # Guide replay (finder, overlay, session)
+β”‚ └── guides/ # Data layer (types, Dexie DB, CRUD)
+β”œβ”€β”€ entrypoints/ # WXT extension entry points
+β”‚ β”œβ”€β”€ background/ # Service worker: state machine + message handlers
+β”‚ β”œβ”€β”€ content.ts # Content script: event capture + rrweb
+β”‚ β”œβ”€β”€ sidepanel/ # Side panel React mount
+β”‚ β”œβ”€β”€ fullview/ # Full-page dashboard mount
+β”‚ β”œβ”€β”€ onboarding/ # First-install wizard
+β”‚ └── options/ # Settings page mount
+β”œβ”€β”€ locales/ # YAML translation files (en, es, pt-BR, fr)
+β”œβ”€β”€ lib/ # Shared utilities (messaging, port, browser API)
+β”œβ”€β”€ stores/ # Zustand state stores
+└── ui/ # React components
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Extension framework | [WXT](https://wxt.dev) (Manifest V3) |
+| Language | TypeScript |
+| UI | React 19 + Tailwind CSS v4 |
+| Components | [shadcn/ui](https://ui.shadcn.com) |
+| State (capture) | [XState](https://xstate.js.org) |
+| State (UI) | [Zustand](https://zustand-demo.pmnd.rs) |
+| Storage | [Dexie.js](https://dexie.org) (IndexedDB) |
+| Messaging | [webext-core](https://webext-core.aklinker1.io) |
+| Session recording | [rrweb](https://www.rrweb.io) |
+| Export | [jsPDF](https://github.com/parallax/jsPDF) + HTML/Markdown |
+| AI (optional) | [Vercel AI SDK](https://sdk.vercel.ai) (OpenAI, Anthropic) |
+| i18n | [@wxt-dev/i18n](https://wxt.dev) + YAML locales |
+| Testing | [Vitest](https://vitest.dev) + Testing Library |
+
+## Pull Request Guidelines
+
+1. Fork the repo and create a branch: `git checkout -b feat/your-feature`
+2. Make your changes and add tests where applicable
+3. Run the full check locally before pushing:
+ ```bash
+ pnpm lint && pnpm test && pnpm build && pnpm build:firefox
+ ```
+4. Use [Conventional Commits](https://www.conventionalcommits.org) for commit messages:
+ - `feat:` new feature
+ - `fix:` bug fix
+ - `docs:` documentation
+ - `test:` tests only
+ - `chore:` tooling/deps
+5. Open a PR with a clear description of what and why
+
+CI (`pr-test.yml`) will run lint, tests, and both browser builds on every PR.
+
+## Adding a Translation
+
+To add a new language:
+
+1. Create `src/locales/{lang-code}.yml` (e.g., `src/locales/de.yml`)
+2. Copy the structure from `src/locales/en.yml`
+3. Translate all values, keeping the keys identical
+4. Keep substitution placeholders (`$1`, `$2`) in the same positions
+5. Build and test: `pnpm build:firefox` (WXT generates types for new locale keys automatically)
+
+## Reporting Bugs
+
+Open an issue with:
+
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Browser + version (Chrome / Firefox)
+- Screenshots if relevant
+- Any errors from the extension console (`chrome://extensions` β†’ Mimik β†’ "service worker" β†’ Console, or Firefox `about:debugging` β†’ Inspect)