|
| 1 | +# Contributing to @mitre/@mitre/nuxt-smartscript |
| 2 | + |
| 3 | +Thank you for your interest in contributing! We welcome contributions from the community and are excited to work with you. |
| 4 | + |
| 5 | +## 🎯 We Welcome PRs! |
| 6 | + |
| 7 | +Whether you're fixing a bug, adding a feature, or improving documentation, we appreciate your contribution. No contribution is too small! |
| 8 | + |
| 9 | +## 📁 Module Architecture |
| 10 | + |
| 11 | +Understanding our architecture helps you contribute effectively: |
| 12 | + |
| 13 | +| File/Directory | Purpose | When to Modify | |
| 14 | +|---------------|---------|----------------| |
| 15 | +| `src/runtime/plugin.ts` | Main plugin orchestrator | When adding new hooks or API methods | |
| 16 | +| `src/runtime/smartscript/types.ts` | TypeScript interfaces | When adding new configuration options | |
| 17 | +| `src/runtime/smartscript/config.ts` | Configuration defaults | When adding new settings | |
| 18 | +| `src/runtime/smartscript/patterns.ts` | Regex patterns | **When adding new text patterns** | |
| 19 | +| `src/runtime/smartscript/processor.ts` | Text processing | When changing how matches are transformed | |
| 20 | +| `src/runtime/smartscript/dom.ts` | DOM utilities | When modifying element creation/manipulation | |
| 21 | +| `src/runtime/smartscript/engine.ts` | Processing engine | When changing the processing flow | |
| 22 | +| `src/runtime/smartscript/errors.ts` | Error handling | When adding new error types | |
| 23 | +| `src/runtime/composables/useSmartScript.ts` | Vue composable | When adding component features | |
| 24 | +| `src/runtime/superscript.css` | Styling | When adjusting visual positioning | |
| 25 | + |
| 26 | +## 🚀 Adding New Capabilities |
| 27 | + |
| 28 | +### Adding a New Pattern (Most Common) |
| 29 | + |
| 30 | +1. **Add pattern to `patterns.ts`:** |
| 31 | +```typescript |
| 32 | +// In createPatterns() |
| 33 | +fractions: /\b(\d+)\/(\d+)\b/g, // Matches 1/2, 3/4, etc. |
| 34 | + |
| 35 | +// In PatternMatchers |
| 36 | +isFraction: (text: string): boolean => /^\d+\/\d+$/.test(text), |
| 37 | +``` |
| 38 | + |
| 39 | +2. **Add processing logic to `processor.ts`:** |
| 40 | +```typescript |
| 41 | +// In processMatch() |
| 42 | +if (PatternMatchers.isFraction(matched)) { |
| 43 | + const [numerator, denominator] = matched.split('/') |
| 44 | + return { |
| 45 | + modified: true, |
| 46 | + parts: [ |
| 47 | + { type: 'super', content: numerator }, |
| 48 | + { type: 'text', content: '⁄' }, // Fraction slash |
| 49 | + { type: 'sub', content: denominator }, |
| 50 | + ], |
| 51 | + } |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +3. **Add test cases to `test/typography.test.ts`:** |
| 56 | +```typescript |
| 57 | +describe('Fractions', () => { |
| 58 | + it('should match fraction patterns', () => { |
| 59 | + const pattern = /\b(\d+)\/(\d+)\b/g |
| 60 | + expect('1/2 cup'.match(pattern)).toEqual(['1/2']) |
| 61 | + }) |
| 62 | +}) |
| 63 | +``` |
| 64 | + |
| 65 | +4. **Update playground example:** |
| 66 | +```vue |
| 67 | +<!-- In playground/app.vue --> |
| 68 | +<section> |
| 69 | + <h2>Fractions</h2> |
| 70 | + <p>Measurements: 1/2 cup, 3/4 teaspoon</p> |
| 71 | +</section> |
| 72 | +``` |
| 73 | + |
| 74 | +### Adding Configuration Options |
| 75 | + |
| 76 | +1. **Update types in `types.ts`:** |
| 77 | +```typescript |
| 78 | +positioning?: { |
| 79 | + fractions?: { |
| 80 | + fontSize?: string |
| 81 | + } |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +2. **Add defaults in `config.ts`:** |
| 86 | +```typescript |
| 87 | +fractions: { |
| 88 | + fontSize: '0.7em' |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +3. **Document in README.md** |
| 93 | + |
| 94 | +## ✅ Testing Guidelines |
| 95 | + |
| 96 | +### Running Tests |
| 97 | +```bash |
| 98 | +# Run all tests |
| 99 | +pnpm test |
| 100 | + |
| 101 | +# Run specific test file |
| 102 | +pnpm test test/typography.test.ts |
| 103 | + |
| 104 | +# Watch mode |
| 105 | +pnpm test:watch |
| 106 | +``` |
| 107 | + |
| 108 | +### Writing Tests |
| 109 | + |
| 110 | +Tests should cover: |
| 111 | +1. **Pattern matching** - Does the regex work? |
| 112 | +2. **Text processing** - Is the output correct? |
| 113 | +3. **Edge cases** - Empty strings, special characters |
| 114 | +4. **Performance** - Large text blocks |
| 115 | + |
| 116 | +Example test structure: |
| 117 | +```typescript |
| 118 | +describe('Feature Name', () => { |
| 119 | + // Test pattern matching |
| 120 | + it('should match expected patterns', () => { |
| 121 | + const pattern = /your-pattern/g |
| 122 | + expect('test input'.match(pattern)).toEqual(['expected']) |
| 123 | + }) |
| 124 | + |
| 125 | + // Test processing |
| 126 | + it('should transform correctly', () => { |
| 127 | + const result = processMatch('input') |
| 128 | + expect(result.parts).toEqual([ |
| 129 | + { type: 'super', content: 'expected' } |
| 130 | + ]) |
| 131 | + }) |
| 132 | + |
| 133 | + // Test edge cases |
| 134 | + it('should handle edge cases', () => { |
| 135 | + expect(processMatch('')).toEqual({ modified: false, parts: [] }) |
| 136 | + }) |
| 137 | +}) |
| 138 | +``` |
| 139 | + |
| 140 | +## 📋 Pull Request Process |
| 141 | + |
| 142 | +### Before Submitting |
| 143 | + |
| 144 | +1. **Fork & Clone** the repository |
| 145 | +2. **Create a feature branch:** `git checkout -b feature/your-feature` |
| 146 | +3. **Make your changes** |
| 147 | +4. **Add/update tests** - All new features need tests |
| 148 | +5. **Run tests:** `pnpm test` - Must pass |
| 149 | +6. **Run linter:** `pnpm lint` - Must pass |
| 150 | +7. **Test in playground:** `pnpm dev` - Verify visually |
| 151 | +8. **Update documentation** if needed |
| 152 | + |
| 153 | +### PR Requirements |
| 154 | + |
| 155 | +Your PR should: |
| 156 | +- ✅ Have a clear title and description |
| 157 | +- ✅ Include tests for new features |
| 158 | +- ✅ Pass all CI checks |
| 159 | +- ✅ Update relevant documentation |
| 160 | +- ✅ Follow existing code style |
| 161 | +- ✅ Be focused on a single feature/fix |
| 162 | + |
| 163 | +### PR Template |
| 164 | +```markdown |
| 165 | +## Description |
| 166 | +Brief description of changes |
| 167 | + |
| 168 | +## Type of Change |
| 169 | +- [ ] Bug fix |
| 170 | +- [ ] New feature |
| 171 | +- [ ] Documentation update |
| 172 | +- [ ] Performance improvement |
| 173 | + |
| 174 | +## Testing |
| 175 | +- [ ] Tests pass locally |
| 176 | +- [ ] Added new tests |
| 177 | +- [ ] Tested in playground |
| 178 | + |
| 179 | +## Screenshots (if applicable) |
| 180 | +Before/after screenshots for visual changes |
| 181 | +``` |
| 182 | + |
| 183 | +## 🎨 Code Style |
| 184 | + |
| 185 | +- Use TypeScript for all new code |
| 186 | +- Follow ESLint rules (auto-fixed on commit) |
| 187 | +- Keep functions small and focused |
| 188 | +- Add JSDoc comments for public APIs |
| 189 | +- Use descriptive variable names |
| 190 | + |
| 191 | +## 🐛 Bug Reports |
| 192 | + |
| 193 | +When reporting bugs, include: |
| 194 | +1. Description of the issue |
| 195 | +2. Steps to reproduce |
| 196 | +3. Expected behavior |
| 197 | +4. Actual behavior |
| 198 | +5. Browser/Node version |
| 199 | +6. Minimal reproduction (CodeSandbox/StackBlitz) |
| 200 | + |
| 201 | +## 💡 Feature Requests |
| 202 | + |
| 203 | +We love new ideas! When requesting features: |
| 204 | +1. Describe the use case |
| 205 | +2. Provide examples |
| 206 | +3. Consider performance impact |
| 207 | +4. Suggest implementation approach (optional) |
| 208 | + |
| 209 | +## 🤝 Getting Help |
| 210 | + |
| 211 | +- Open an issue for questions |
| 212 | +- Tag with `help wanted` or `question` |
| 213 | +- Join discussions in issues/PRs |
| 214 | +- Contact: saf@mitre.org |
| 215 | + |
| 216 | +## 📝 Development Workflow |
| 217 | + |
| 218 | +```bash |
| 219 | +# 1. Install dependencies |
| 220 | +pnpm install |
| 221 | + |
| 222 | +# 2. Start dev server |
| 223 | +pnpm dev |
| 224 | + |
| 225 | +# 3. Make changes & test |
| 226 | +pnpm test |
| 227 | + |
| 228 | +# 4. Lint & format |
| 229 | +pnpm lint --fix |
| 230 | + |
| 231 | +# 5. Build |
| 232 | +pnpm prepack |
| 233 | + |
| 234 | +# 6. Commit with conventional commits |
| 235 | +git commit -m "feat: add fraction support" |
| 236 | +``` |
| 237 | + |
| 238 | +## 🏆 Recognition |
| 239 | + |
| 240 | +Contributors are recognized in: |
| 241 | +- GitHub contributors page |
| 242 | +- Release notes |
| 243 | +- Special thanks in documentation |
| 244 | + |
| 245 | +Thank you for making @mitre/@mitre/nuxt-smartscript better! 🎉 |
0 commit comments