# Contributing Guidelines — EmberDocs **IMPORTANT:** This file, `claude.md`, and `.cursorrules` must stay in sync. See "Sync Instructions" at bottom. **For universal development standards applicable to any project, see:** `dev-docs/guides/DEVELOPMENT-STANDARDS.md` --- ## Universal Standards (Apply to All Projects) See `dev-docs/guides/DEVELOPMENT-STANDARDS.md` for comprehensive details on: - **Code Style:** TypeScript strict, Prettier, ESLint, naming conventions - **Testing:** Unit/integration/E2E pyramid, Jest, coverage targets ≥70% - **Git & Version Control:** Conventional Commits, branch strategy, semantic versioning - **Pull Requests:** Requirements (tests, docs, scope), code review checklist - **Security:** Input validation, secrets management, dependency auditing - **Accessibility:** WCAG 2.1 Level AA minimum - **Documentation:** Progress logs, architecture decisions, API docs - **License Compliance:** Automated license checking, NOTICES.md maintenance, dependency license verification - **CI/CD:** Standard build pipeline, GitHub Actions, deployment strategy --- ## Contributing Workflow (EmberDocs) ### 1. Getting Started ```bash # Clone repository git clone https://github.com/sturdy-barnacle/emberdocs.git cd emberdocs # Install dependencies npm install # Create .env.local from template cp .env.example .env.local # Run dev server npm run dev # Open http://localhost:3000 in browser ``` **First-time setup checklist:** - [ ] Repo cloned and dependencies installed - [ ] Dev server running at http://localhost:3000 - [ ] All tests pass: `npm run check` - [ ] Read `dev-docs/Quick-Reference.md` (5 min) - [ ] Reviewed Phase 01 deliverables in `dev-docs/planning/mvp_phase01of02.md` - [ ] Checked locked decisions in `dev-docs/guides/ARCHITECTURE-DECISIONS.md` - [ ] Configured Git user: `git config user.name "Your Name"` --- ### 2. Create a Feature Branch ```bash # Update main branch git fetch origin git checkout main git pull origin main # Create feature branch git checkout -b feature/search-indexing # For new features git checkout -b fix/parser-crash # For bug fixes git checkout -b chore/update-dependencies # For chores/docs ``` **Branch naming rules:** - `feature/` — New feature or enhancement - `fix/` — Bug fix - `chore/` — Documentation, dependencies, config changes - Use kebab-case: `feature/add-dark-mode`, not `feature/addDarkMode` --- ### 3. Make Changes **While developing:** ```bash # Run dev server in background npm run dev & # In another terminal, run tests in watch mode npm test -- --watch # Check code quality npm run lint # Format code npm run format # Type check npm run typecheck ``` **Code organization:** - Keep changes focused (one feature per branch) - Put code in `src/app/` or `src/lib/` - Create tests in `__tests__/` or as `*.test.ts` files - Update relevant docs (progress, architecture, user guides) **Write tests as you code:** ```bash # Example: Testing a parser npm test -- src/lib/parse-markdown.test.ts --watch ``` --- ### 4. Commit Your Changes **Before committing, run:** ```bash npm run check # Full CI suite (lint → typecheck → test → build) ``` **Commit with clear messages (Conventional Commits):** ```bash git commit -m "feat(parser): add YAML frontmatter extraction - Parse YAML header from markdown files - Validate frontmatter against schema - Extract body content after frontmatter Closes #42" ``` **Commit message format:** ``` ():