Skip to content

Commit e6f8c4c

Browse files
mikebarkminmikebarkmin
authored
Merge pull request #7 from openpatch/copilot/set-up-copilot-instructions
[WIP] Set up Copilot instructions for repository
2 parents a3b1d88 + df9d649 commit e6f8c4c

1 file changed

Lines changed: 201 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Copilot Instructions for Learningmap
2+
3+
## Project Overview
4+
5+
Learningmap is an open-source tool for creating, sharing, and exploring learning pathways. It's a monorepo built with React, TypeScript, and pnpm workspaces.
6+
7+
- **Website**: https://learningmap.app
8+
- **Documentation**: https://learningmap.openpatch.org
9+
- **Repository**: https://github.com/openpatch/learningmap
10+
- **Maintainer**: Mike Barkmin (@mikebarkmin)
11+
12+
## Repository Structure
13+
14+
This is a **pnpm monorepo** with multiple packages and platforms:
15+
16+
```
17+
learningmap/
18+
├── packages/
19+
│ ├── learningmap/ # Core React component library
20+
│ └── web-component/ # Web component wrapper
21+
├── platforms/
22+
│ └── web/ # Web application (learningmap.app)
23+
├── docs/ # Documentation (Hyperbook)
24+
└── scripts/ # Build and development scripts
25+
```
26+
27+
## Tech Stack
28+
29+
- **Language**: TypeScript
30+
- **UI Framework**: React 19
31+
- **Package Manager**: pnpm (required - version >= 8)
32+
- **Build Tool**: Vite + esbuild
33+
- **Visual Editor**: ReactFlow (@xyflow/react)
34+
- **Layout Engine**: ELK.js for auto-layout
35+
- **Testing**: Vitest
36+
- **Documentation**: Hyperbook
37+
- **Version Management**: Changesets
38+
- **Code Quality**: Prettier, Husky
39+
40+
## Development Workflow
41+
42+
### Installation and Setup
43+
44+
```bash
45+
pnpm install # Install all dependencies
46+
pnpm build # Build all packages
47+
pnpm test # Run tests across all packages
48+
pnpm lint # Type-check with TypeScript
49+
pnpm docs:dev # Start documentation dev server
50+
pnpm dev # Watch mode for development
51+
```
52+
53+
### Making Changes
54+
55+
1. **Always use pnpm** - The project enforces pnpm usage via preinstall hook
56+
2. **Build before testing** - Packages depend on each other's built artifacts
57+
3. **Use Changesets** - For version management and changelog generation
58+
4. **Follow existing patterns** - Match code style and structure of existing files
59+
60+
### Package Scripts
61+
62+
Each package has its own scripts defined in its `package.json`:
63+
64+
- `build`: Compiles TypeScript and bundles with esbuild
65+
- `lint`: Type-checks with TypeScript (tsc --noEmit)
66+
- `test`: Runs tests with Vitest
67+
68+
## Code Style and Conventions
69+
70+
### TypeScript
71+
72+
- Use strict TypeScript with proper type definitions
73+
- Prefer interfaces for props and types for unions/intersections
74+
- Export types alongside components
75+
- No implicit `any` - always define types
76+
77+
### React Components
78+
79+
- Use functional components with hooks
80+
- Prefer named exports for components
81+
- Use TypeScript interfaces for component props
82+
- Follow existing patterns for event handlers (e.g., `on` prefix)
83+
- Keep components focused and modular
84+
85+
### File Organization
86+
87+
- Components in PascalCase (e.g., `EditorToolbar.tsx`)
88+
- Utilities and helpers in camelCase (e.g., `helper.ts`, `translations.ts`)
89+
- Index files export public API
90+
- Keep related code together
91+
92+
### Translations
93+
94+
The project supports internationalization (i18n):
95+
96+
- Translations are defined in `packages/learningmap/src/translations.ts`
97+
- Use the `getTranslations(language)` helper
98+
- Default language is English (`en`), German (`de`) is also supported
99+
- Always add translations for both languages when adding new strings
100+
101+
## Common Tasks
102+
103+
### Adding a New Feature
104+
105+
1. Implement the feature in the appropriate package
106+
2. Add TypeScript types for all new props/interfaces
107+
3. Update translations if adding user-facing text
108+
4. Consider both editor and viewer modes
109+
5. Test in both debug and preview modes
110+
6. Update documentation if it's a public API change
111+
112+
### Working with the Editor
113+
114+
The core editor (`LearningMapEditor`) has two modes:
115+
116+
- **Edit Mode**: Full editing capabilities with toolbar
117+
- **Preview Mode**: View-only mode for testing the learner experience
118+
119+
Key components:
120+
121+
- `EditorToolbar`: Main menu and controls
122+
- `EditorDrawer`: Side panel for node/edge editing
123+
- Node types: `TopicNode`, `TaskNode`, `TextNode`, `ImageNode`
124+
- Edge types: Regular edges, completion edges, unlock edges
125+
126+
### Styling
127+
128+
- CSS is bundled with components
129+
- Use existing CSS classes and patterns
130+
- Follow the visual design of existing components
131+
- Test in both light and dark modes (if applicable)
132+
133+
## Testing
134+
135+
- Tests are run with Vitest
136+
- Test files should be placed alongside source files
137+
- Currently minimal test coverage - focus on core functionality
138+
- Run tests with `pnpm test` before submitting PRs
139+
140+
## Documentation
141+
142+
Documentation is built with Hyperbook and located in the `docs/` directory:
143+
144+
- `docs/book/index.md`: Main documentation entry
145+
- `docs/book/development.md`: Development guide
146+
- `docs/book/contributing.md`: Contribution guidelines
147+
- Update docs when adding features that affect the public API
148+
149+
## CI/CD
150+
151+
GitHub Actions workflows:
152+
153+
- `pull-request.yml`: Runs tests and build on PRs
154+
- `changeset-version.yml`: Manages version bumps and releases
155+
- `docs.yml`: Deploys documentation
156+
157+
All PRs must pass:
158+
159+
1. TypeScript type checking (`pnpm lint`)
160+
2. Tests (`pnpm test`)
161+
3. Build (`pnpm build`)
162+
163+
## Important Notes
164+
165+
- **No force pushes** - Git force push is disabled
166+
- **No rebase** - Use merge commits for combining branches
167+
- **Minimal changes** - Make the smallest possible changes to achieve goals
168+
- **Preserve working code** - Don't remove or modify working code unless necessary
169+
- **Follow existing patterns** - Match the style and structure of existing code
170+
- **Use ecosystem tools** - Prefer pnpm scripts and package tools over manual changes
171+
172+
## Dependencies
173+
174+
When adding new dependencies:
175+
176+
- Add to the appropriate package's `package.json`
177+
- Use `pnpm add <package>` in the package directory
178+
- Consider bundle size impact for the web component
179+
- Prefer peer dependencies for React and related packages
180+
181+
## Common Pitfalls
182+
183+
- ❌ Don't use `npm` or `yarn` - always use `pnpm`
184+
- ❌ Don't commit built artifacts (`dist/` folders)
185+
- ❌ Don't modify `node_modules` or `pnpm-lock.yaml` manually
186+
- ❌ Don't skip the build step - packages depend on each other
187+
- ❌ Don't add tests that don't exist - follow existing test patterns
188+
- ✅ Do run `pnpm install` after pulling changes
189+
- ✅ Do run `pnpm build` before running tests
190+
- ✅ Do commit your changes using the Changesets workflow
191+
- ✅ Do test in both editor and preview modes
192+
193+
## Getting Help
194+
195+
- **Issues**: Open an issue on GitHub for bugs or feature requests
196+
- **Community**: Join the Matrix community at https://matrix.to/#/#openpatch:matrix.org
197+
- **Contact**: Reach out to contact@openpatch.org for support
198+
199+
## License
200+
201+
MIT License - maintained by OpenPatch (https://openpatch.org)

0 commit comments

Comments
 (0)