Skip to content

Commit 9256ef5

Browse files
hatemhosnyhatemhosny
committed
contribution guide
1 parent 4a4db9a commit 9256ef5

2 files changed

Lines changed: 216 additions & 8 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -121,14 +121,18 @@ If you would like to contribute to the project for the first time, please consid
121121

122122
Also, all questions are [welcomed](https://github.com/live-codes/livecodes/discussions).
123123

124-
## Specific Topics
125-
126-
- [Adding Languages](./docs/docs/contribution/adding-languages.mdx)
127-
- [i18n](./docs/docs/contribution/i18n.mdx)
128-
- [Compiler System](./docs/docs/contribution/compiler-system.mdx)
129-
- [Build System](./docs/docs/contribution/build-system.mdx)
130-
- [Storybook](./docs/docs/contribution/storybook.mdx)
131-
- [Release](./docs/docs/contribution/release.mdx)
124+
## System Documentation
125+
126+
For detailed documentation on specific systems, see the [Contribution Guide](./docs/docs/contribution/README.md) which includes comprehensive documentation for:
127+
128+
- **Core Systems**: Architecture, Compiler, Config, Storage
129+
- **Editor & UI**: Editor System, UI Design, Tools Pane
130+
- **Language Support**: Adding Languages, Type Loader
131+
- **Features**: Import/Export, Result Page, Code Formatting
132+
- **Services & Infrastructure**: Services, Build System
133+
- **Internationalization**: i18n workflow
134+
- **Testing & Development**: Storybook setup
135+
- **Release**: Release workflow and version management
132136

133137
## Funding
134138

‎docs/docs/contribution/README.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# LiveCodes Contribution Guide
2+
3+
This directory contains comprehensive documentation for contributors working on the LiveCodes codebase. Each document covers a specific system or aspect of the application.
4+
5+
**New to contributing?** Start with the [beginner-friendly introduction](../../../CONTRIBUTING.md), including setup instructions, pull request guidelines, and code of conduct.
6+
7+
## Quick Start
8+
9+
1. Read the [Architecture Overview](./architecture.mdx) first to understand the high-level design
10+
2. Review the [Build System](./build-system.mdx) to understand how the project is built
11+
3. Check the [Code Style](#code-style) section below for coding conventions
12+
13+
## Documentation Index
14+
15+
### Core Systems
16+
17+
| Document | Description |
18+
| -------------------------------------------- | ------------------------------------------------------------------------- |
19+
| [architecture.mdx](./architecture.mdx) | High-level architecture overview with diagrams of all major systems |
20+
| [compiler-system.mdx](./compiler-system.mdx) | Language compilation pipeline, worker architecture, and import resolution |
21+
| [config-system.mdx](./config-system.mdx) | Configuration management, validation, and URL parameter handling |
22+
| [storage-system.mdx](./storage-system.mdx) | Client-side storage using IndexedDB and localStorage |
23+
24+
### Editor & UI
25+
26+
| Document | Description |
27+
| ---------------------------------------------------- | ------------------------------------------------------------- |
28+
| [editor-system.mdx](./editor-system.mdx) | Multi-editor support (Monaco, CodeMirror, CodeJar) and themes |
29+
| [ui-design-system.mdx](./ui-design-system.mdx) | UI components, styling, theming, and responsive design |
30+
| [tools-pane-system.mdx](./tools-pane-system.mdx) | Console, compiled code viewer, and test runner |
31+
| [notifications-system.md](./notifications-system.md) | Toast notification system |
32+
33+
### Language Support
34+
35+
| Document | Description |
36+
| ------------------------------------------------------------ | -------------------------------------------------- |
37+
| [language-support-system.mdx](./language-support-system.mdx) | Language specifications, processors, and utilities |
38+
| [adding-languages.mdx](./adding-languages.mdx) | Step-by-step guide to add new language support |
39+
| [type-loader-system.mdx](./type-loader-system.mdx) | TypeScript type acquisition for IntelliSense |
40+
41+
### Features
42+
43+
| Document | Description |
44+
| ---------------------------------------------------------- | --------------------------------------------------------- |
45+
| [import-system.mdx](./import-system.mdx) | Import from GitHub, GitLab, files, URLs, and more |
46+
| [export-system.mdx](./export-system.mdx) | Export to JSON, ZIP, HTML, CodePen, JSFiddle, GitHub Gist |
47+
| [result-page.mdx](./result-page.mdx) | Result iframe generation and sandbox creation |
48+
| [code-formatting-system.mdx](./code-formatting-system.mdx) | Prettier integration and custom formatters |
49+
50+
### Services & Infrastructure
51+
52+
| Document | Description |
53+
| -------------------------------------------- | ---------------------------------------------------------- |
54+
| [services-system.mdx](./services-system.mdx) | External services: auth, share, CDN resolution, CORS proxy |
55+
| [build-system.mdx](./build-system.mdx) | Build scripts, outputs, and development workflow |
56+
57+
### Internationalization
58+
59+
| Document | Description |
60+
| ---------------------- | ---------------------------------------------------------------- |
61+
| [i18n.mdx](./i18n.mdx) | Translation workflow, Lokalise integration, and script reference |
62+
63+
### Testing & Development
64+
65+
| Document | Description |
66+
| -------------------------------- | ----------------------------------------- |
67+
| [storybook.mdx](./storybook.mdx) | Storybook setup for SDK component testing |
68+
69+
### Release
70+
71+
| Document | Description |
72+
| ---------------------------- | --------------------------------------- |
73+
| [release.mdx](./release.mdx) | Release workflow and version management |
74+
75+
## Code Style
76+
77+
LiveCodes follows specific coding conventions documented in `AGENTS.md` at the repository root. Key points:
78+
79+
### Formatting (Prettier)
80+
81+
- Semicolons: always
82+
- Single quotes
83+
- Trailing commas: all
84+
- Print width: 100
85+
86+
### Imports
87+
88+
Use `import type` for type-only imports:
89+
90+
```typescript
91+
import type { Config, Language } from '../models';
92+
import { someFunction } from '../utils';
93+
```
94+
95+
### Naming Conventions
96+
97+
- **Files/directories:** kebab-case (`build-config.ts`)
98+
- **Functions/variables:** camelCase (`createEventsManager`)
99+
- **Types/interfaces:** PascalCase (`CompileResult`)
100+
- **No enums:** use string union types
101+
102+
### Functions and Exports
103+
104+
- Arrow function constants preferred
105+
- Named exports only (no default exports)
106+
- No classes in application code
107+
- Use factory functions (`createXxx()`)
108+
- One variable per statement
109+
110+
### Testing
111+
112+
Tests are co-located in `__tests__/` directories:
113+
114+
```typescript
115+
import { debounce } from '..';
116+
117+
describe('utils', () => {
118+
test('debounce', async () => {
119+
expect(num).toBe(1);
120+
});
121+
});
122+
```
123+
124+
## Running Tests
125+
126+
```bash
127+
npm run test # Run all tests (typecheck + lint + unit)
128+
npm run test:unit # Run Jest unit tests only
129+
npm run test:unit -- --testPathPattern="compiler" # Run specific tests
130+
npm run e2e # Run Playwright e2e tests
131+
npm run typecheck:app # TypeScript type check
132+
npm run lint:eslint # ESLint check
133+
npm run fix # Auto-fix all linting issues
134+
```
135+
136+
## Development Workflow
137+
138+
```bash
139+
npm run start # Dev server with watch (http://127.0.0.1:8080)
140+
npm run build # Full production build
141+
npm run docs # Start documentation server (http://localhost:3000/docs)
142+
npm run storybook # Start storybook (http://localhost:6006)
143+
```
144+
145+
## Architecture Overview
146+
147+
```mermaid
148+
flowchart TD
149+
subgraph "Core"
150+
A[core.ts<br/>Main Application]
151+
B[config/<br/>Configuration]
152+
C[storage/<br/>Persistence]
153+
D[events/<br/>Event System]
154+
end
155+
156+
subgraph "Editors"
157+
E[monaco.ts]
158+
F[codemirror.ts]
159+
G[codejar.ts]
160+
end
161+
162+
subgraph "Compilation"
163+
H[compiler/<br/>Worker-based]
164+
I[languages/<br/>Language Specs]
165+
J[formatter/<br/>Prettier + Custom]
166+
end
167+
168+
subgraph "UI"
169+
K[UI/<br/>App Controllers]
170+
L[html/<br/>Templates]
171+
M[toolspane/<br/>Console/Tests]
172+
end
173+
174+
subgraph "Services"
175+
N[auth.ts]
176+
O[share.ts]
177+
P[modules.ts]
178+
Q[sandbox.ts]
179+
end
180+
181+
A --> B & C & D
182+
A --> E & F & G
183+
A --> H
184+
H --> I
185+
A --> J
186+
A --> K
187+
K --> L
188+
A --> M
189+
A --> N & O & P & Q
190+
```
191+
192+
## Key Design Principles
193+
194+
1. **Client-side only** - All compilation happens in the browser
195+
2. **Worker-based compilation** - Heavy work off main thread
196+
3. **Lazy loading** - Compilers and editors loaded on demand
197+
4. **Modular architecture** - Factory functions, no classes
198+
5. **Type safety** - Strict TypeScript with explicit types
199+
200+
## Getting Help
201+
202+
- Open an issue: [GitHub Issues](https://github.com/live-codes/livecodes/issues)
203+
- Discussion: [GitHub Discussions](https://github.com/live-codes/livecodes/discussions)
204+
- Documentation: [livecodes.io/docs](https://livecodes.io/docs)

0 commit comments

Comments
 (0)