Skip to content

Commit 8875689

Browse files
mikebarkminmikebarkmin
authored
Merge pull request #39 from openpatch/copilot/update-docs-folder
Add comprehensive documentation for React and web component packages
2 parents 2b89357 + ab57ae7 commit 8875689

4 files changed

Lines changed: 1154 additions & 0 deletions

File tree

‎docs/book/contributing.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,108 @@ index: 2
44
---
55

66
# Contributing
7+
8+
Thank you for your interest in contributing to Learningmap! This guide will help you get started.
9+
10+
## Code of Conduct
11+
12+
By participating in this project, you agree to abide by our [Code of Conduct](https://github.com/openpatch/learningmap/blob/main/CODE_OF_CONDUCT.md).
13+
14+
## How Can I Contribute?
15+
16+
### Reporting Bugs
17+
18+
Before creating bug reports, please check the [existing issues](https://github.com/openpatch/learningmap/issues) to avoid duplicates.
19+
20+
When creating a bug report, include:
21+
- A clear and descriptive title
22+
- Steps to reproduce the behavior
23+
- Expected behavior
24+
- Actual behavior
25+
- Screenshots (if applicable)
26+
- Your environment (browser, OS, Node.js version)
27+
28+
### Suggesting Enhancements
29+
30+
Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:
31+
- A clear and descriptive title
32+
- A detailed description of the proposed feature
33+
- Explain why this enhancement would be useful
34+
- If possible, provide examples of how it would work
35+
36+
### Pull Requests
37+
38+
1. **Fork the repository** and create your branch from `main`
39+
2. **Set up your development environment** (see [Development](/development))
40+
3. **Make your changes** following our coding standards
41+
4. **Add tests** if you're adding functionality
42+
5. **Run linting and tests**:
43+
```bash
44+
pnpm lint
45+
pnpm test
46+
pnpm build
47+
```
48+
6. **Create a changeset**:
49+
```bash
50+
pnpm exec changeset
51+
```
52+
Follow the prompts to describe your changes
53+
7. **Commit your changes** with a clear commit message
54+
8. **Push to your fork** and submit a pull request
55+
56+
## Development Guidelines
57+
58+
### Code Style
59+
60+
- Follow the existing code style in the repository
61+
- Use TypeScript with proper type definitions
62+
- Run Prettier before committing (automatic with Husky)
63+
- Keep components focused and modular
64+
65+
### Commit Messages
66+
67+
- Use clear and descriptive commit messages
68+
- Start with a verb in present tense (e.g., "Add", "Fix", "Update")
69+
- Reference issues and PRs when relevant
70+
71+
### Testing
72+
73+
- Write tests for new features
74+
- Ensure existing tests pass
75+
- Follow existing test patterns
76+
- Run `pnpm test` before submitting
77+
78+
### Documentation
79+
80+
- Update documentation when adding features
81+
- Add JSDoc comments for public APIs
82+
- Update the changelog via changesets
83+
84+
## Project Structure
85+
86+
```
87+
learningmap/
88+
├── packages/
89+
│ ├── learningmap/ # Core React component library
90+
│ └── web-component/ # Web component wrapper
91+
├── platforms/
92+
│ └── web/ # Web application
93+
├── docs/ # Documentation
94+
└── scripts/ # Build scripts
95+
```
96+
97+
## Making Your First Contribution
98+
99+
Not sure where to start? Look for issues labeled:
100+
- `good first issue` - Good for newcomers
101+
- `help wanted` - Extra attention is needed
102+
103+
## Getting Help
104+
105+
- **GitHub Issues**: For bugs and feature requests
106+
- **Matrix Community**: Join us at https://matrix.to/#/#openpatch:matrix.org
107+
- **Email**: contact@openpatch.org
108+
109+
## License
110+
111+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎docs/book/development.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,134 @@ index: 1
44
---
55

66
# Development
7+
8+
This guide will help you set up your development environment for working on Learningmap.
9+
10+
## Prerequisites
11+
12+
- **Node.js**: Version 18 or higher
13+
- **pnpm**: Version 8 or higher (required - the project enforces pnpm usage)
14+
15+
## Installation
16+
17+
1. Clone the repository:
18+
```bash
19+
git clone https://github.com/openpatch/learningmap.git
20+
cd learningmap
21+
```
22+
23+
2. Install dependencies:
24+
```bash
25+
pnpm install
26+
```
27+
28+
3. Build all packages:
29+
```bash
30+
pnpm build
31+
```
32+
33+
## Repository Structure
34+
35+
Learningmap is a **pnpm monorepo** with the following structure:
36+
37+
```
38+
learningmap/
39+
├── packages/
40+
│ ├── learningmap/ # Core React component library
41+
│ └── web-component/ # Web component wrapper
42+
├── platforms/
43+
│ └── web/ # Web application (learningmap.app)
44+
├── docs/ # Documentation (Hyperbook)
45+
└── scripts/ # Build and development scripts
46+
```
47+
48+
## Development Workflow
49+
50+
### Available Scripts
51+
52+
From the root directory:
53+
54+
- `pnpm dev` - Watch mode for development (rebuilds on file changes)
55+
- `pnpm build` - Build all packages
56+
- `pnpm test` - Run tests across all packages
57+
- `pnpm lint` - Type-check with TypeScript
58+
- `pnpm docs:dev` - Start documentation dev server (http://localhost:3000)
59+
- `pnpm docs:build` - Build documentation
60+
61+
### Working on Packages
62+
63+
Each package has its own scripts:
64+
65+
- `pnpm build` - Build the package
66+
- `pnpm lint` - Type-check with TypeScript
67+
- `pnpm test` - Run tests with Vitest
68+
69+
**Important**: Always build packages before testing, as packages depend on each other's built artifacts.
70+
71+
### Development Mode
72+
73+
For active development with automatic rebuilds:
74+
75+
```bash
76+
pnpm dev
77+
```
78+
79+
This starts a watcher that rebuilds packages when you make changes.
80+
81+
### Documentation
82+
83+
To work on documentation:
84+
85+
```bash
86+
pnpm docs:dev
87+
```
88+
89+
The documentation is built with [Hyperbook](https://hyperbook.openpatch.org) and is located in the `docs/` directory.
90+
91+
## Testing Your Changes
92+
93+
1. **Type-check**: `pnpm lint`
94+
2. **Run tests**: `pnpm test`
95+
3. **Build**: `pnpm build`
96+
97+
All PRs must pass these checks.
98+
99+
## Tech Stack
100+
101+
- **Language**: TypeScript
102+
- **UI Framework**: React 19
103+
- **Build Tool**: Vite + esbuild
104+
- **Visual Editor**: ReactFlow (@xyflow/react)
105+
- **Layout Engine**: ELK.js for auto-layout
106+
- **Testing**: Vitest
107+
- **Code Quality**: Prettier, Husky
108+
109+
## Version Management
110+
111+
This project uses [Changesets](https://github.com/changesets/changesets) for version management:
112+
113+
1. Make your changes
114+
2. Run `pnpm exec changeset` to create a changeset
115+
3. Follow the prompts to describe your changes
116+
4. Commit the changeset file with your PR
117+
118+
## Common Issues
119+
120+
### pnpm not found
121+
Install pnpm globally:
122+
```bash
123+
npm install -g pnpm
124+
```
125+
126+
### Build failures
127+
Make sure all dependencies are installed:
128+
```bash
129+
pnpm install
130+
pnpm build
131+
```
132+
133+
### TypeScript errors
134+
Run type-checking to see all errors:
135+
```bash
136+
pnpm lint
137+
```

0 commit comments

Comments
 (0)