-
Notifications
You must be signed in to change notification settings - Fork 37
added onboarding documentation #31
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
kozachokv
wants to merge
1
commit into
koldovsky:main
Choose a base branch
from
kozachokv:patch-1
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,280 @@ | ||
| # Task 01 | ||
| # Excalidraw Engineering Onboarding Guide | ||
|
|
||
| - Create onboarding documentation for the project (or part you are working on) for a new employees. Use texts, diagrams | ||
| - Evaluate parts of your project in tokens | ||
| - Fork this repository and make pull request with solution | ||
| This guide is for new engineers, especially developers with limited open-source/monorepo experience. It explains what this repository contains, how it is organized, and how to start making safe contributions quickly. | ||
|
|
||
| --- | ||
|
|
||
| ## 1) What this project is | ||
|
|
||
| Excalidraw is an open-source, hand-drawn style virtual whiteboard. | ||
|
|
||
| This repository is a monorepo that contains: | ||
| - The reusable React editor library published as `@excalidraw/excalidraw` | ||
| - The production web app (`excalidraw-app`) powering excalidraw.com | ||
| - Supporting internal packages (`@excalidraw/common`, `@excalidraw/element`, `@excalidraw/math`, `@excalidraw/utils`) | ||
| - Integration examples and documentation sources | ||
|
|
||
| Core user-facing capabilities include: | ||
| - Infinite canvas drawing and diagramming | ||
| - Local-first behavior | ||
| - Export/import of drawing data | ||
| - Real-time collaboration (app side) | ||
| - End-to-end encryption for collaboration features | ||
|
|
||
| --- | ||
|
|
||
| ## 2) Monorepo architecture at a glance | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| A[excalidraw-monorepo] --> B[packages/excalidraw<br/>React editor library] | ||
| A --> C[excalidraw-app<br/>Web app] | ||
| A --> D[packages/common] | ||
| A --> E[packages/element] | ||
| A --> F[packages/math] | ||
| A --> G[packages/utils] | ||
| A --> H[examples/*] | ||
| A --> I[dev-docs] | ||
|
|
||
| C --> B | ||
| B --> D | ||
| B --> E | ||
| B --> F | ||
| B --> G | ||
| ``` | ||
|
|
||
| ### Directory map | ||
|
|
||
| - `packages/excalidraw/`: main editor implementation and package entrypoints | ||
| - `excalidraw-app/`: app-specific integrations (hosting, app services, runtime env, etc.) | ||
| - `packages/common/`: shared constants/types/utilities used across packages | ||
| - `packages/element/`: element logic (geometry, transforms, element-level operations) | ||
| - `packages/math/`: math helpers (vectors, geometry primitives) | ||
| - `packages/utils/`: export/utility helpers for consumers | ||
| - `examples/`: reference integrations (for example Next.js) | ||
| - `dev-docs/`: docs site content and contributor docs | ||
| - `.github/workflows/`: CI/CD automation and repository checks | ||
|
|
||
| --- | ||
|
|
||
| ## 3) Technical stack | ||
|
|
||
| ### Runtime and languages | ||
| - TypeScript (strict mode enabled) | ||
| - React 19 | ||
| - Node.js `>=18.0.0` | ||
| - Yarn workspaces (package manager pinned to `yarn@1.22.22`) | ||
|
|
||
| ### Build/dev tooling | ||
| - Vite for app dev/build | ||
| - esbuild-based package build scripts | ||
| - Vitest for tests | ||
| - jsdom as browser-like test environment | ||
|
|
||
| ### Quality tooling | ||
| - ESLint (`@excalidraw/eslint-config` + `react-app`) | ||
| - Prettier (`@excalidraw/prettier-config`) | ||
| - Husky + lint-staged for pre-commit checks | ||
| - EditorConfig for baseline editor consistency | ||
|
|
||
| ### App/platform dependencies (selected) | ||
| - Firebase | ||
| - Socket.IO client | ||
| - Sentry | ||
| - i18n/language detection tooling | ||
|
|
||
| --- | ||
|
|
||
| ## 4) Dependency and import model | ||
|
|
||
| The workspace uses TypeScript path aliases and matching Vitest aliases so internal packages can be imported as `@excalidraw/*` during development. | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| A[Code in monorepo] --> B[@excalidraw/common] | ||
| A --> C[@excalidraw/element] | ||
| A --> D[@excalidraw/math] | ||
| A --> E[@excalidraw/utils] | ||
| A --> F[@excalidraw/excalidraw] | ||
| B --> G[packages/common/src] | ||
| C --> H[packages/element/src] | ||
| D --> I[packages/math/src] | ||
| E --> J[packages/utils/src] | ||
| F --> K[packages/excalidraw] | ||
| ``` | ||
|
|
||
| Important convention: | ||
| - In `packages/excalidraw`, avoid barrel self-imports from `@excalidraw/excalidraw` and prefer direct relative imports for implementation modules. | ||
|
|
||
| --- | ||
|
|
||
| ## 5) Daily development workflow | ||
|
|
||
| ### 5.1 First setup | ||
|
|
||
| 1. Install prerequisites: | ||
| - Node.js 18+ | ||
| - Yarn | ||
| - Git | ||
| 2. Clone repo | ||
| 3. Install dependencies: | ||
| - `yarn` | ||
| 4. Start app locally: | ||
| - `yarn start` | ||
| 5. Open: | ||
| - `http://localhost:3000` | ||
|
|
||
| ### 5.2 Main commands you will use | ||
|
|
||
| - `yarn start`: run app in development mode | ||
| - `yarn test`: run tests (Vitest) | ||
| - `yarn test:update`: update snapshots + run tests without watch | ||
| - `yarn test:typecheck`: TypeScript type check | ||
| - `yarn test:code`: ESLint checks | ||
| - `yarn test:other`: Prettier check mode | ||
| - `yarn fix`: auto-format and lint-fix where possible | ||
| - `yarn build`: app production build | ||
| - `yarn build:packages`: build internal packages | ||
|
|
||
| ### 5.3 Recommended "before PR" checklist | ||
|
|
||
| - Run `yarn test:update` | ||
| - Run `yarn test:typecheck` | ||
| - Run `yarn test:code` | ||
| - Run `yarn test:other` | ||
| - Manually test changed behavior locally | ||
|
|
||
| --- | ||
|
|
||
| ## 6) Contribution workflow | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| A[Pick issue / discuss change] --> B[Create feature branch] | ||
| B --> C[Implement change] | ||
| C --> D[Run tests + typecheck + lint] | ||
| D --> E[Manual verification in app] | ||
| E --> F[Open PR with semantic title] | ||
| F --> G[CI checks and review] | ||
| G --> H[Merge] | ||
| ``` | ||
|
|
||
| Guidelines: | ||
| - Prefer small, focused PRs | ||
| - Follow semantic PR title prefixes such as: | ||
| - `feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `ci`, `chore` | ||
| - Add tests for bug fixes and new behavior | ||
| - If scope is large, open/align on an issue first | ||
|
|
||
| --- | ||
|
|
||
| ## 7) CI/CD and automation overview | ||
|
|
||
| This repository uses GitHub Actions to enforce quality and automate releases/deployments. | ||
|
|
||
| Important workflows include: | ||
| - `lint.yml`: lint + type checks | ||
| - `test.yml`: test execution | ||
| - `test-coverage-pr.yml`: coverage reporting | ||
| - `size-limit.yml`: package size control | ||
| - `semantic-pr-title.yml`: PR title convention check | ||
| - Release/deployment workflows for package and docker pipelines | ||
|
|
||
| What this means for you: | ||
| - Local checks should match CI expectations | ||
| - If CI fails, reproduce locally with the matching command and fix before re-requesting review | ||
|
|
||
| --- | ||
|
|
||
| ## 8) Code style and best practices | ||
|
|
||
| ### Formatting and style | ||
| - 2-space indentation, LF endings, UTF-8, trailing whitespace trimmed | ||
| - Keep imports consistently ordered (lint-enforced) | ||
| - Use `import type` where appropriate (lint-enforced) | ||
|
|
||
| ### Architecture and design habits | ||
| - Keep package boundaries clean (do not couple app-specific logic into reusable package layers) | ||
| - Prefer small, composable functions over large monolithic logic | ||
| - Preserve backward compatibility for public package APIs | ||
| - Place logic in the most specific package that owns the concern | ||
|
|
||
| ### Testing habits | ||
| - Add regression tests when fixing bugs | ||
| - Update snapshots only when the behavior change is intentional | ||
| - Do not skip manual testing for interaction-heavy UI changes | ||
|
|
||
| ### PR and review habits | ||
| - Explain "why" in PR description, not just "what changed" | ||
| - Call out risky areas and what was tested | ||
| - Keep commits understandable and scoped | ||
|
|
||
| --- | ||
|
|
||
| ## 9) How to orient quickly in the codebase | ||
|
|
||
| If you are new and unsure where to start: | ||
|
|
||
| 1. Read: | ||
| - `README.md` | ||
| - `dev-docs/docs/introduction/development.mdx` | ||
| - `dev-docs/docs/introduction/contributing.mdx` | ||
| 2. Run app and interact with core flows in browser | ||
| 3. Pick one small issue (docs/easy/fix) and trace code path end-to-end | ||
| 4. For feature work: | ||
| - start from UI action handler | ||
| - follow state/data flow to element/data modules | ||
| - verify export/import and rendering effects if touched | ||
|
|
||
| --- | ||
|
|
||
| ## 10) Common beginner pitfalls (and how to avoid them) | ||
|
|
||
| - Editing the wrong package: | ||
| - confirm if change belongs to reusable editor (`packages/excalidraw`) or app shell (`excalidraw-app`) | ||
| - Forgetting full quality checks: | ||
| - run typecheck/lint/tests before PR | ||
| - Accidentally introducing boundary leaks: | ||
| - keep app-specific dependencies out of shared packages | ||
| - Snapshot churn: | ||
| - review snapshot diffs carefully; never update blindly | ||
| - Missing manual verification: | ||
| - canvas/editor behavior often needs interactive validation, not just unit tests | ||
|
|
||
| --- | ||
|
|
||
| ## 11) Suggested first-week plan for a new engineer | ||
|
|
||
| Day 1: | ||
| - Set up environment | ||
| - Run app, tests, and typecheck | ||
| - Read onboarding + contributing docs | ||
|
|
||
| Day 2-3: | ||
| - Shadow one merged PR and trace impacted modules | ||
| - Fix one small issue (docs or low-risk bug) | ||
|
|
||
| Day 4-5: | ||
| - Implement a scoped improvement with tests | ||
| - Submit PR with semantic title and clear test notes | ||
|
|
||
| By end of week 1, goal is confidence in: | ||
| - Monorepo navigation | ||
| - Local quality pipeline | ||
| - Safe contribution flow | ||
|
|
||
| --- | ||
|
|
||
| ## 12) Handy reference list | ||
|
|
||
| - Root project overview: `README.md` | ||
| - Contribution entrypoint: `CONTRIBUTING.md` | ||
| - Development setup guide: `dev-docs/docs/introduction/development.mdx` | ||
| - Contribution guide: `dev-docs/docs/introduction/contributing.mdx` | ||
| - Main editor package docs: `packages/excalidraw/README.md` | ||
| - Root scripts and workspace config: `package.json` | ||
| - TypeScript aliases/config: `tsconfig.json` | ||
| - Lint rules: `.eslintrc.json` | ||
| - Formatting rules: `.editorconfig` | ||
| - Test config and thresholds: `vitest.config.mts` | ||
|
|
||
| - | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🧩 Analysis chain
🏁 Script executed:
Repository: koldovsky/is-01-docs
Length of output: 640
Update README to remove references to non-existent workflows and config files, or add the missing files.
Verification found that all workflow files referenced in this section are missing:
lint.yml,test.yml,test-coverage-pr.yml,size-limit.yml, andsemantic-pr-title.yml. Most referenced config/doc files also don't exist (only README.md was found). This creates a significant onboarding problem—new contributors following the README will search for these files and hit dead ends.Either remove the references to workflows/configs that don't exist, or ensure the files are present and paths are correct.
🤖 Prompt for AI Agents