|
| 1 | +# Contributing to @mheob/config |
| 2 | + |
| 3 | +Thank you for your interest in contributing to this project! This document provides guidelines and instructions for contributing. |
| 4 | + |
| 5 | +## Getting Started |
| 6 | + |
| 7 | +### Prerequisites |
| 8 | + |
| 9 | +- Node.js >= 22.20.0 |
| 10 | +- pnpm 10.18.1 |
| 11 | + |
| 12 | +### Setup |
| 13 | + |
| 14 | +1. Fork and clone the repository |
| 15 | +2. Install dependencies: |
| 16 | + |
| 17 | + ```bash |
| 18 | + pnpm install |
| 19 | + ``` |
| 20 | + |
| 21 | +3. Build all packages: |
| 22 | + |
| 23 | + ```bash |
| 24 | + pnpm build |
| 25 | + ``` |
| 26 | + |
| 27 | +## Development Workflow |
| 28 | + |
| 29 | +### Making Changes |
| 30 | + |
| 31 | +1. Create a new branch from `main`: |
| 32 | + |
| 33 | + ```bash |
| 34 | + git checkout -b feat/your-feature-name |
| 35 | + ``` |
| 36 | + |
| 37 | +2. Make your changes in the relevant package(s) under `packages/` |
| 38 | + |
| 39 | +3. Test your changes: |
| 40 | + |
| 41 | + ```bash |
| 42 | + pnpm build |
| 43 | + pnpm lint |
| 44 | + pnpm test |
| 45 | + ``` |
| 46 | + |
| 47 | +### Commit Guidelines |
| 48 | + |
| 49 | +This project uses [Conventional Commits](https://www.conventionalcommits.org/) with the following types: |
| 50 | + |
| 51 | +- `feat`: New features |
| 52 | +- `fix`: Bug fixes |
| 53 | +- `docs`: Documentation changes |
| 54 | +- `style`: Code style changes (formatting, etc.) |
| 55 | +- `refactor`: Code refactoring |
| 56 | +- `perf`: Performance improvements |
| 57 | +- `test`: Adding or updating tests |
| 58 | +- `build`: Build system changes |
| 59 | +- `ci`: CI/CD changes |
| 60 | +- `chore`: Other changes that don't modify src or test files |
| 61 | +- `revert`: Revert previous commits |
| 62 | + |
| 63 | +**Commit message format:** |
| 64 | + |
| 65 | +```text |
| 66 | +<type>(<scope>): <subject> |
| 67 | +
|
| 68 | +<body> |
| 69 | +
|
| 70 | +<footer> |
| 71 | +``` |
| 72 | + |
| 73 | +**Example:** |
| 74 | + |
| 75 | +```text |
| 76 | +feat(eslint): add new rule for import sorting |
| 77 | +
|
| 78 | +Added eslint-plugin-import-x configuration to enforce |
| 79 | +consistent import ordering across all projects. |
| 80 | +
|
| 81 | +Closes #123 |
| 82 | +``` |
| 83 | + |
| 84 | +**Important:** |
| 85 | + |
| 86 | +- Keep the subject line under 50 characters |
| 87 | +- Use imperative mood ("add" not "added") |
| 88 | +- No period at the end of the subject |
| 89 | +- Reference issues in the footer |
| 90 | + |
| 91 | +### Creating Changesets |
| 92 | + |
| 93 | +For any user-facing changes, create a changeset: |
| 94 | + |
| 95 | +```bash |
| 96 | +pnpm changeset |
| 97 | +``` |
| 98 | + |
| 99 | +Follow the prompts to: |
| 100 | + |
| 101 | +1. Select which packages are affected |
| 102 | +2. Choose the bump type (major, minor, patch) |
| 103 | +3. Write a clear summary of the changes |
| 104 | + |
| 105 | +**When to create changesets:** |
| 106 | + |
| 107 | +- New features (minor) |
| 108 | +- Bug fixes (patch) |
| 109 | +- Breaking changes (major) |
| 110 | +- Documentation updates that affect package usage (patch) |
| 111 | + |
| 112 | +**Skip changesets for:** |
| 113 | + |
| 114 | +- Internal refactoring |
| 115 | +- Test updates |
| 116 | +- CI/CD changes |
| 117 | +- Repository maintenance |
| 118 | + |
| 119 | +## Code Quality |
| 120 | + |
| 121 | +### Linting |
| 122 | + |
| 123 | +All code must pass ESLint checks: |
| 124 | + |
| 125 | +```bash |
| 126 | +pnpm lint |
| 127 | +``` |
| 128 | + |
| 129 | +The pre-commit hook will automatically lint staged files. |
| 130 | + |
| 131 | +### Spell Checking |
| 132 | + |
| 133 | +Run cspell to check for typos: |
| 134 | + |
| 135 | +```bash |
| 136 | +pnpm cspell |
| 137 | +``` |
| 138 | + |
| 139 | +Add project-specific terms to `.cspell.json` if needed. |
| 140 | + |
| 141 | +## Package Structure |
| 142 | + |
| 143 | +Each package should have: |
| 144 | + |
| 145 | +```text |
| 146 | +packages/your-package/ |
| 147 | +├── src/ |
| 148 | +│ └── index.ts # Main entry point |
| 149 | +├── package.json # Package manifest |
| 150 | +├── README.md # Package documentation |
| 151 | +├── tsconfig.json # TypeScript config |
| 152 | +└── LICENSE # MIT license |
| 153 | +``` |
| 154 | + |
| 155 | +### Package.json Requirements |
| 156 | + |
| 157 | +- `name`: Must follow `@mheob/<package-name>` pattern |
| 158 | +- `version`: Managed by changesets |
| 159 | +- `exports`: Define proper entry points |
| 160 | +- `files`: Include only necessary files in npm package |
| 161 | +- `repository`: Link to monorepo |
| 162 | +- `license`: MIT |
| 163 | + |
| 164 | +## Testing |
| 165 | + |
| 166 | +Before submitting a PR: |
| 167 | + |
| 168 | +1. Build all packages: `pnpm build` |
| 169 | +2. Run linting: `pnpm lint` |
| 170 | +3. Run spell check: `pnpm cspell` |
| 171 | +4. Test in a local project if possible |
| 172 | + |
| 173 | +## Pull Request Process |
| 174 | + |
| 175 | +1. Ensure all tests pass and code is linted |
| 176 | +2. Create a changeset if needed |
| 177 | +3. Update documentation if required |
| 178 | +4. Push your branch and create a pull request |
| 179 | +5. Fill out the PR template completely |
| 180 | +6. Link any related issues |
| 181 | +7. Wait for review and address feedback |
| 182 | + |
| 183 | +### PR Title Format |
| 184 | + |
| 185 | +Use conventional commit format: |
| 186 | + |
| 187 | +```text |
| 188 | +feat(package-name): add new feature |
| 189 | +``` |
| 190 | + |
| 191 | +### Review Process |
| 192 | + |
| 193 | +- At least one maintainer approval is required |
| 194 | +- CI checks must pass |
| 195 | +- Kodiak bot may auto-merge approved PRs |
| 196 | + |
| 197 | +## Release Process |
| 198 | + |
| 199 | +Releases are handled by maintainers: |
| 200 | + |
| 201 | +1. Merge changesets to main |
| 202 | +2. CI creates a "Version Packages" PR |
| 203 | +3. Maintainer merges the version PR |
| 204 | +4. CI automatically publishes to npm |
| 205 | + |
| 206 | +## Project-Specific Guidelines |
| 207 | + |
| 208 | +### ESLint Config |
| 209 | + |
| 210 | +- Follow the existing rule structure |
| 211 | +- Group related rules together |
| 212 | +- Add comments for non-obvious configurations |
| 213 | +- Test with various project types |
| 214 | + |
| 215 | +### Prettier Config |
| 216 | + |
| 217 | +- Maintain consistency with existing style |
| 218 | +- Document any opinionated choices |
| 219 | +- Consider impact on existing users |
| 220 | + |
| 221 | +### Commitlint Config |
| 222 | + |
| 223 | +- Keep rules aligned with conventional commits spec |
| 224 | +- Document custom scopes and types |
| 225 | + |
| 226 | +## Getting Help |
| 227 | + |
| 228 | +- Check existing issues and discussions |
| 229 | +- Review documentation in package READMEs |
| 230 | +- Ask questions in issue comments |
| 231 | +- Reach out to maintainers if needed |
| 232 | + |
| 233 | +## License |
| 234 | + |
| 235 | +By contributing, you agree that your contributions will be licensed under the MIT License. |
0 commit comments