# Contributing Guide [← Back to Developer Guide](./index.md) --- How to contribute code to ProPresenter Lyrics Export. ## Code of Conduct - Be respectful and inclusive - Provide constructive feedback - Assume good intent - Respect maintainer decisions ## Getting Started 1. **Fork** the repository 2. **Clone** your fork: `git clone https://github.com/YOUR_GITHUB_NAME/propresenterlyricexport.git` 3. **Create branch**: `git checkout -b feature/my-feature` 4. **Make changes** and test thoroughly 5. **Submit PR** with description ## Development Process ### Before Starting ```bash # Install dependencies npm install # Run tests npm test # Verify setup npm start -- status ``` ### Making Changes 1. **Create feature branch** (not on main) ```bash git checkout -b feature/descriptive-name ``` 2. **Make atomic commits** - One logical change per commit ```bash git add src/file.ts git commit -m "feat: Brief description - Detailed explanation - What and why, not how - Reference issues if applicable" ``` 3. **Test both paths** (if changing core logic) ```bash npm run build # Compile npm start -- status # Test CLI npm run electron:dev # Test desktop ``` 4. **Run linter and tests** ```bash npm run lint npm test ``` ## Code Style ### TypeScript Standards - **Strict mode enabled** - No `any` types - **Explicit types** - Annotate function parameters and returns - **No semicolons** - Follow existing style - **Functional approach** - Prefer const/pure functions **Example:** ```typescript // ✅ Good export async function exportPlaylist( playlistId: string, options: ExportOptions ): Promise { const items = await fetchItems(playlistId); return processItems(items, options); } // ❌ Bad async function exportPlaylist(playlistId, options) { // No type annotations var items = await fetchItems(playlistId); // var keyword return processItems(items, options); } ``` ### File Organization - **One export per file** (usually) - **Descriptive filenames** - `song-matcher.ts` not `util.ts` - **Clear folder structure** - Related code together - **Import order:** 1. External dependencies 2. Internal modules 3. Relative paths 4. Type imports **Example:** ```typescript import fs from 'fs'; import { PlaylistExporter } from '../services/playlist-exporter'; import { formatDate } from './utils'; import type { Playlist } from '../types/playlist'; ``` ### Naming Conventions - **Functions:** `camelCase` - `exportPlaylist()` - **Classes:** `PascalCase` - `PlaylistExporter` - **Constants:** `UPPER_SNAKE_CASE` - `DEFAULT_PORT` - **Private methods:** `_leading_underscore` - `_formatText()` - **Booleans:** `is`, `has`, `can` prefix - `isActive`, `hasError` ### Comments Use comments sparingly - code should be self-documenting. **Good comments:** ```typescript // ProPresenter API timeout (10 seconds) // This is intentionally long to allow slow network connections const API_TIMEOUT_MS = 10000; // BUG: PPT export breaks with fonts > 200pt // TODO: Fix when upgrading pptxgenjs beyond 3.10.0 ``` **Bad comments:** ```typescript // Loop through items items.forEach(item => { // Process the item process(item); }); ``` ## Git Workflow ### Commit Messages Follow [Conventional Commits](https://www.conventionalcommits.org/): ``` ():