@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.6

package/docs/Contributing.md

@@ -0,0 +1,626 @@
+# Contributing Guide
+
+How to contribute to the Mixtape Design System.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Git Workflow](#git-workflow)
+- [Commit Conventions](#commit-conventions)
+- [Pull Request Process](#pull-request-process)
+- [Code Review](#code-review)
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js**: v20 or later
+- **pnpm**: v9 or later
+- **Git**: Latest version
+
+### Initial Setup
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/previousnext/mxds.git
+cd mxds
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Start development server
+pnpm dev
+
+# 4. Open Storybook
+# HTML: http://localhost:6006
+# React: http://localhost:6008
+```
+
+### Project Structure
+
+```
+mxds/
+├── src/
+│   ├── Atom/           # Atomic components
+│   ├── Component/      # Complex components
+│   ├── Form/          # Form elements
+│   ├── Layout/        # Layout components
+│   └── Utility/       # Utilities and helpers
+├── docs/              # Documentation
+├── mockups/           # Page mockups
+└── dist/              # Build output (generated)
+```
+
+---
+
+## Development Workflow
+
+### 1. Create a New Component
+
+Don't hand-create the files — use the scaffolding CLI, which generates all of them (React/Twig/Web-Component/stories/Figma Code Connect stub/README) following [Component Architecture](./ComponentArchitecture.md)'s conventions and wires the new component into `src/elements.ts`/`src/react.ts` for you:
+
+```bash
+# Dry-run first to see the file list without writing anything
+pnpm scaffold-component Component MyComponent --dry-run
+
+# Then for real
+pnpm scaffold-component Component MyComponent
+```
+
+Omit `--react`/`--webcomponent`/`--twig` to generate all three formats (the default), or pass specific flags to scaffold only what's needed. If you're using an AI assistant, the `create-mxds-component` skill drives this same CLI and walks through filling in the generated stubs.
+
+### 2. Develop Component
+
+```bash
+# Start Storybook in watch mode
+pnpm dev
+
+# Edit files with live reload
+# - Write component code
+# - Add styles
+# - Create stories
+# - Test in Storybook
+```
+
+### 3. Test Component
+
+```bash
+# Run linting
+pnpm lint
+
+# Run tests
+pnpm test
+
+# Fix formatting
+pnpm format
+
+# Type check
+pnpm lint-ts
+```
+
+### 4. Build
+
+```bash
+# Build for production
+pnpm build
+
+# Build Storybook only
+pnpm build-storybook
+
+# Build Vite only
+pnpm build-vite
+```
+
+---
+
+## Git Workflow
+
+### Branching Strategy
+
+```bash
+# Feature branch
+git checkout -b feature/add-carousel
+
+# Bug fix branch
+git checkout -b fix/button-hover-state
+
+# Documentation branch
+git checkout -b docs/update-readme
+
+# Refactor branch
+git checkout -b refactor/simplify-tabs
+```
+
+### Branch Naming
+
+| Type          | Prefix      | Example                  |
+| ------------- | ----------- | ------------------------ |
+| New feature   | `feature/`  | `feature/add-tooltip`    |
+| Bug fix       | `fix/`      | `fix/accordion-overflow` |
+| Documentation | `docs/`     | `docs/api-reference`     |
+| Refactoring   | `refactor/` | `refactor/button-styles` |
+| Performance   | `perf/`     | `perf/optimize-images`   |
+| Tests         | `test/`     | `test/add-snapshots`     |
+| Chore         | `chore/`    | `chore/update-deps`      |
+
+### Working on a Branch
+
+```bash
+# 1. Create and switch to branch
+git checkout -b feature/my-feature
+
+# 2. Make changes
+# ... edit files ...
+
+# 3. Stage changes
+git add .
+
+# 4. Commit with Commitizen
+pnpm commit
+
+# 5. Push to remote
+git push origin feature/my-feature
+
+# 6. Create Pull Request on GitHub
+```
+
+---
+
+## Commit Conventions
+
+### Using Commitizen
+
+We use **Commitizen** for standardized commit messages:
+
+```bash
+# Instead of git commit, use:
+pnpm commit
+
+# Follow the prompts:
+# 1. Select type (feat, fix, docs, etc.)
+# 2. Enter scope (optional)
+# 3. Write short description
+# 4. Write longer description (optional)
+# 5. List breaking changes (if any)
+# 6. Reference issues (if any)
+```
+
+### Commit Types
+
+| Type       | Description             | Example                           |
+| ---------- | ----------------------- | --------------------------------- |
+| `feat`     | New feature             | `feat: add tooltip component`     |
+| `fix`      | Bug fix                 | `fix: resolve button hover state` |
+| `docs`     | Documentation only      | `docs: update API reference`      |
+| `style`    | Code style (formatting) | `style: fix indentation`          |
+| `refactor` | Code refactoring        | `refactor: simplify tabs logic`   |
+| `perf`     | Performance improvement | `perf: optimize image loading`    |
+| `test`     | Adding/updating tests   | `test: add snapshot tests`        |
+| `build`    | Build system changes    | `build: update vite config`       |
+| `ci`       | CI configuration        | `ci: add GitHub Actions`          |
+| `chore`    | Maintenance tasks       | `chore: update dependencies`      |
+| `revert`   | Revert previous commit  | `revert: revert "feat: add X"`    |
+
+### Commit Message Format
+
+```
+type(scope): subject
+
+body
+
+footer
+```
+
+**Examples:**
+
+```bash
+# Simple commit
+feat: add carousel component
+
+# With scope
+fix(button): resolve hover state issue
+
+# With body
+feat: add tooltip component
+
+Add a reusable tooltip component with positioning
+options and accessibility features.
+
+# With breaking change
+feat!: update button API
+
+BREAKING CHANGE: Button now requires 'variant' prop
+instead of 'type'. Update all usage to:
+<Button variant="primary">Click</Button>
+
+# With issue reference
+fix: resolve accordion overflow
+
+Fixes #123
+```
+
+### Commit Best Practices
+
+✅ **Do:**
+
+- Use present tense ("add feature" not "added feature")
+- Use imperative mood ("move cursor" not "moves cursor")
+- Keep subject line under 50 characters
+- Capitalize subject line
+- Don't end subject line with period
+- Separate subject from body with blank line
+- Wrap body at 72 characters
+- Reference issues/PRs in footer
+
+❌ **Don't:**
+
+- Commit unrelated changes together
+- Use vague messages ("fix stuff", "updates")
+- Include WIP commits in PR
+- Forget to reference breaking changes
+
+---
+
+## Pull Request Process
+
+### Before Creating PR
+
+```bash
+# 1. Update from main
+git checkout main
+git pull origin main
+git checkout your-branch
+git merge main
+
+# 2. Fix any issues
+pnpm format
+
+# 3. Run full test suite
+pnpm lint
+pnpm test
+
+# 4. Build to ensure no errors
+pnpm build
+
+# 5. Update snapshots if needed
+pnpm test -- -u
+
+# 6. Commit any fixes
+pnpm commit
+
+# 7. Push to remote
+git push origin your-branch
+```
+
+### Creating the PR
+
+1. **Go to GitHub** and create Pull Request
+2. **Fill out template** with:
+   - Description of changes
+   - Motivation and context
+   - Type of change
+   - Checklist completion
+   - Screenshots (if UI change)
+   - Related issues
+
+### PR Template
+
+```markdown
+## Description
+
+Brief description of what this PR does.
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] Code follows style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex code
+- [ ] Documentation updated
+- [ ] No new warnings generated
+- [ ] Tests added/updated
+- [ ] All tests passing
+- [ ] Snapshots reviewed and updated
+- [ ] A11y violations = 0
+- [ ] Storybook stories added
+
+## Screenshots (if applicable)
+
+Before:
+After:
+
+## Related Issues
+
+Closes #123
+```
+
+### PR Best Practices
+
+✅ **Do:**
+
+- Keep PRs small and focused
+- Write descriptive title and description
+- Add screenshots for UI changes
+- Request specific reviewers
+- Respond to feedback promptly
+- Update PR based on reviews
+- Keep PR up to date with main
+- Test locally before requesting review
+
+❌ **Don't:**
+
+- Submit WIP code
+- Mix unrelated changes
+- Ignore review feedback
+- Force push after reviews start
+- Merge without approval
+- Skip CI checks
+
+---
+
+## Code Review
+
+### As a Reviewer
+
+**What to check:**
+
+1. ✅ **Code quality** - Follows guidelines
+2. ✅ **Functionality** - Works as described
+3. ✅ **Tests** - Adequate coverage
+4. ✅ **Documentation** - Updated if needed
+5. ✅ **Performance** - No obvious issues
+6. ✅ **Security** - No vulnerabilities
+7. ✅ **Accessibility** - WCAG compliant
+8. ✅ **Browser compatibility** - Works cross-browser
+
+**Review process:**
+
+```bash
+# 1. Check out PR branch
+gh pr checkout 123
+
+# 2. Install dependencies
+pnpm install
+
+# 3. Start Storybook
+pnpm dev
+
+# 4. Test manually
+# - Try all variants
+# - Test keyboard nav
+# - Check responsive
+
+# 5. Run tests
+pnpm lint
+pnpm test
+
+# 6. Leave review on GitHub
+# - Approve, Request changes, or Comment
+# - Be specific and constructive
+```
+
+**Review comments:**
+
+```markdown
+# ✅ Good feedback
+
+Suggestion: Consider using AbortController here for cleanup.
+See: docs/MemoryManagement.md#event-listeners
+
+# ❌ Poor feedback
+
+This is wrong.
+```
+
+### As the Author
+
+**Responding to feedback:**
+
+- ✅ Thank reviewers for their time
+- ✅ Ask questions if unclear
+- ✅ Implement requested changes
+- ✅ Explain decisions if disagreeing
+- ✅ Mark conversations as resolved
+- ✅ Request re-review after changes
+
+**Making changes:**
+
+```bash
+# 1. Make changes based on feedback
+# ... edit files ...
+
+# 2. Commit changes
+pnpm commit
+
+# 3. Push to same branch
+git push origin your-branch
+
+# PR automatically updates!
+
+# 4. Re-request review on GitHub
+```
+
+---
+
+## Release Process
+
+### Version Bumping
+
+```bash
+# Patch version (0.0.x) - Bug fixes
+pnpm bump-version
+
+# Minor version (0.x.0) - New features
+pnpm version minor -m "chore: tag %s"
+
+# Major version (x.0.0) - Breaking changes
+pnpm version major -m "chore: tag %s"
+```
+
+### Publishing
+
+```bash
+# 1. Ensure main is up to date
+git checkout main
+git pull origin main
+
+# 2. Bump version
+pnpm bump-version
+
+# 3. Build for production
+pnpm build-ci
+
+# 4. Publish to npm
+pnpm publish
+
+# 5. Push tags
+git push --tags
+```
+
+---
+
+## Common Tasks
+
+### Adding a New Component
+
+```bash
+# 1. Scaffold the component (see "Create a New Component" above)
+pnpm scaffold-component Component MyComponent
+
+# 2. Fill in the generated stubs
+# - Real props/markup/CSS, story variants, README content
+
+# 3. Test
+pnpm dev
+pnpm format
+pnpm lint-classes
+pnpm audit-parity --component MyComponent
+pnpm test
+
+# 4. Commit
+pnpm commit
+```
+
+### Updating Dependencies
+
+```bash
+# Check outdated packages
+pnpm outdated
+
+# Update all dependencies
+pnpm update
+
+# Update to latest versions
+pnpm update --latest
+
+# Check for security issues
+pnpm audit
+
+# Fix security issues
+pnpm audit --fix
+
+# Commit
+pnpm commit
+```
+
+### Fixing a Bug
+
+```bash
+# 1. Create bug fix branch
+git checkout -b fix/describe-bug
+
+# 2. Reproduce bug
+# - Add failing test if possible
+# - Document steps in PR
+
+# 3. Fix bug
+# - Make minimal changes
+# - Don't refactor unrelated code
+
+# 4. Verify fix
+pnpm test
+
+# 5. Update tests/snapshots
+pnpm test -- -u
+
+# 6. Commit
+pnpm commit
+
+# 7. Create PR
+```
+
+---
+
+## Getting Help
+
+### Resources
+
+- **Documentation**: [docs/README.md](./README.md)
+- **Storybook**: https://mxds.pnx.io
+- **GitHub Issues**: https://github.com/previousnext/mxds/issues
+- **Slack**: #mixtape (internal)
+
+### Questions?
+
+- 💬 Ask in Slack: #mixtape (internal)
+- 🐛 Report bugs in Issues
+- 💡 Suggest features in Issues
+- 📧 Email: rikki.bochow@previousnext.com.au
+
+---
+
+## Code of Conduct
+
+### Our Pledge
+
+We are committed to providing a welcoming and inspiring community for all.
+
+### Our Standards
+
+✅ **Expected behavior:**
+
+- Be respectful and inclusive
+- Welcome newcomers
+- Accept constructive criticism
+- Focus on what's best for the community
+
+❌ **Unacceptable behavior:**
+
+- Harassment or discrimination
+- Trolling or insulting comments
+- Personal or political attacks
+- Publishing others' private information
+
+### Enforcement
+
+Report issues to: rikki.bochow@previousnext.com.au
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same license as the project.
+
+---
+
+## Thank You! 🎉
+
+Thank you for contributing to the Mixtape Design System! Your contributions help make the web more accessible and consistent for everyone.
+
+---
+
+## Related Documentation
+
+- [Code Quality Guidelines](./CodeQuality.md)
+- [Component Architecture](./ComponentArchitecture.md)
+- [Testing Guide](./Testing.md)
+- [API Documentation](./API.md)