@@ -22,28 +22,49 @@ cd omniscript-core
2222git checkout -b my-feature-branch
2323```
2424
25- ### 3️⃣ Install dependencies (if applicable)
25+ ### 3️⃣ Install dependencies
2626
2727``` bash
28- # For example, if using Node.js
29- npm install
28+ # Install pnpm if you haven't already
29+ npm install -g pnpm
30+
31+ # Install project dependencies
32+ pnpm install
33+
34+ # Build all packages
35+ pnpm run build
3036```
3137
3238### 4️⃣ Make your changes
3339
34- - Follow the coding style used in the repo (we will provide linting configs
35- soon).
36- - Add/update tests where relevant.
37- - Update documentation if needed.
38-
39- ### 5️⃣ Run tests
40+ - Follow the coding style enforced by ESLint and Prettier
41+ - Add/update tests where relevant
42+ - Update documentation if needed
43+ - Ensure type safety with TypeScript
4044
41- Before running the test suite, make sure all dependencies are installed:
45+ ### 5️⃣ Run quality checks
4246
4347``` bash
44- npm install
45- npm test
46- # or cargo test / pytest etc., depending on the language used
48+ # Run all tests
49+ pnpm test
50+
51+ # Run tests in watch mode
52+ pnpm run test:watch
53+
54+ # Check code coverage
55+ pnpm run test:coverage
56+
57+ # Type checking
58+ pnpm run typecheck
59+
60+ # Lint your code
61+ pnpm run lint
62+
63+ # Format your code
64+ pnpm run format
65+
66+ # Or run all checks at once
67+ pnpm run lint && pnpm run typecheck && pnpm test
4768```
4869
4970### 6️⃣ Commit and push
@@ -71,11 +92,59 @@ Write examples and test documents ✅ Improve documentation, READMEs, and guides
7192
7293## ✨ Guidelines
7394
74- - All PRs should target the ` main ` branch unless directed otherwise.
75- - Write clear, descriptive commit messages (e.g.,
76- ` fix: handle nested bullets in slides ` ).
77- - Include tests for new functionality when possible.
78- - All contributors must follow our [ Code of Conduct] ( CODE_OF_CONDUCT.md ) .
95+ ### Commit Message Convention
96+
97+ We follow the [ Conventional Commits] ( https://www.conventionalcommits.org/ ) specification:
98+
99+ - ` feat: ` - A new feature
100+ - ` fix: ` - A bug fix
101+ - ` docs: ` - Documentation only changes
102+ - ` style: ` - Code style changes (formatting, missing semicolons, etc.)
103+ - ` refactor: ` - Code refactoring without changing functionality
104+ - ` perf: ` - Performance improvements
105+ - ` test: ` - Adding or updating tests
106+ - ` chore: ` - Maintenance tasks, dependencies, etc.
107+ - ` ci: ` - CI/CD configuration changes
108+
109+ ** Examples:**
110+ ```
111+ feat: add @diagram block support
112+ fix: handle nested bullets in slides properly
113+ docs: update CLI usage examples
114+ test: add tests for formula parsing
115+ ```
116+
117+ ### Code Style
118+
119+ - ** TypeScript** : Use strict mode with proper type annotations
120+ - ** Formatting** : Automatically handled by Prettier (run ` pnpm run format ` )
121+ - ** Linting** : Follow ESLint rules (run ` pnpm run lint ` )
122+ - ** Naming** : Use camelCase for variables/functions, PascalCase for classes/types
123+
124+ ### Testing Requirements
125+
126+ - All new features must include tests
127+ - Aim for 80%+ code coverage
128+ - Write both unit tests and integration tests where applicable
129+ - Test edge cases and error handling
130+
131+ ### Pull Request Process
132+
133+ 1 . All PRs should target the ` main ` branch unless directed otherwise
134+ 2 . Fill out the PR template completely
135+ 3 . Ensure all CI checks pass (tests, linting, type checking)
136+ 4 . Request review from maintainers
137+ 5 . Address any review feedback
138+ 6 . Once approved, maintainers will merge your PR
139+
140+ ### Code Review Guidelines
141+
142+ - Be respectful and constructive in feedback
143+ - Focus on code quality, not personal preferences
144+ - Explain the "why" behind suggestions
145+ - Approve PRs that meet the project standards
146+
147+ ### All contributors must follow our [ Code of Conduct] ( CODE_OF_CONDUCT.md )
79148
80149---
81150
@@ -90,6 +159,73 @@ the future of intelligent, interoperable documents!
90159
91160---
92161
162+ ## 📚 Development Resources
163+
164+ ### Project Structure
165+
166+ ```
167+ omniscript-core/
168+ ├── parser/ # Core OSF parsing library
169+ ├── cli/ # Command-line interface
170+ ├── spec/ # OSF specification versions
171+ ├── examples/ # Example OSF documents
172+ ├── tests/ # Test suites
173+ └── docs/ # Documentation
174+
175+ omniscript-converters/
176+ └── src/ # Format conversion implementations
177+
178+ omniscript-vscode/
179+ └── # VSCode extension (in development)
180+
181+ omniscript-site/
182+ └── # Documentation website (in development)
183+ ```
184+
185+ ### Key Technologies
186+
187+ - ** Language** : TypeScript 5.x
188+ - ** Package Manager** : pnpm
189+ - ** Testing** : Vitest
190+ - ** Linting** : ESLint 9.x
191+ - ** Formatting** : Prettier 3.x
192+ - ** Build** : TypeScript Compiler (tsc)
193+ - ** CI/CD** : GitHub Actions
194+
195+ ### Useful Commands
196+
197+ ``` bash
198+ # Development
199+ pnpm run dev # Watch mode for development
200+
201+ # Building
202+ pnpm run build # Build all packages
203+ pnpm run clean # Clean build artifacts
204+
205+ # Testing
206+ pnpm test # Run tests
207+ pnpm run test:watch # Watch mode testing
208+ pnpm run test:coverage # Coverage report
209+
210+ # Code Quality
211+ pnpm run lint # Lint and fix
212+ pnpm run format # Format code
213+ pnpm run typecheck # Type checking
214+
215+ # CLI Testing
216+ cd cli/dist
217+ node index.js parse ../../examples/rich_demo.osf
218+ ```
219+
220+ ### Getting Help
221+
222+ - 📖 Read the [ documentation] ( docs/spec-v0.5-overview.md )
223+ - 💬 Ask in [ GitHub Discussions] ( https://github.com/OmniScriptOSF/omniscript-core/discussions )
224+ - 🐛 Report issues using [ issue templates] ( .github/ISSUE_TEMPLATE/ )
225+ - 📧 Contact maintainer: [ @alpha912 ] ( https://github.com/alpha912 )
226+
227+ ---
228+
93229## 📄 License & Ownership
94230
95231By contributing, you agree that your contributions will be licensed under the
0 commit comments