|
| 1 | +# Contributing to JSON Schema Form Element |
| 2 | + |
| 3 | +Thank you for your interest in contributing to JSFE! This document will guide you through the process of setting up the development environment and submitting your contributions. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +Before you begin, ensure you have the following installed: |
| 8 | + |
| 9 | +- [Node.js](https://nodejs.org/) (version 20 LTS or later) |
| 10 | +- [pnpm](https://pnpm.io/) (version 9.12.3 or later) |
| 11 | +- Git |
| 12 | + |
| 13 | +## Getting Started |
| 14 | + |
| 15 | +1. Fork the repository on GitHub |
| 16 | +2. Clone your fork locally: |
| 17 | + |
| 18 | + ```bash |
| 19 | + git clone https://github.com/YOUR_USERNAME/jsfe.git |
| 20 | + cd jsfe |
| 21 | + ``` |
| 22 | + |
| 23 | +3. Launch the local CI to bootstrap the monorepo and to check that everything is OK on your machine: |
| 24 | + ```bash |
| 25 | + ./local-ci.sh |
| 26 | + ``` |
| 27 | + |
| 28 | +## Development Workflow |
| 29 | + |
| 30 | +1. Create a new branch for your feature/fix: |
| 31 | + |
| 32 | + ```bash |
| 33 | + git checkout -b feat/your-feature-name |
| 34 | + # or |
| 35 | + git checkout -b fix/your-fix-name |
| 36 | + ``` |
| 37 | + |
| 38 | +2. Start the development tasks: |
| 39 | + |
| 40 | + ```bash |
| 41 | + pnpm dev |
| 42 | + ``` |
| 43 | + |
| 44 | +3. Make your changes and ensure they follow our coding standards: |
| 45 | + |
| 46 | + ```bash |
| 47 | + # Run linting |
| 48 | + pnpm lint |
| 49 | + |
| 50 | + # Fix linting issues |
| 51 | + pnpm lint:fix |
| 52 | + |
| 53 | + # Check formatting |
| 54 | + pnpm format:check |
| 55 | + |
| 56 | + # Fix formatting |
| 57 | + pnpm format |
| 58 | + ``` |
| 59 | + |
| 60 | +4. Run tests: |
| 61 | + |
| 62 | + ```bash |
| 63 | + # Run unit tests |
| 64 | + pnpm test:unit |
| 65 | + |
| 66 | + # Run e2e tests |
| 67 | + pnpm test:e2e |
| 68 | + |
| 69 | + # Run tests in watch mode during development |
| 70 | + pnpm test:unit:dev |
| 71 | + pnpm test:e2e:dev |
| 72 | + ``` |
| 73 | + |
| 74 | +## Commit Guidelines |
| 75 | + |
| 76 | +We follow [Conventional Commits](https://www.conventionalcommits.org/) specification. Your commit messages should be structured as follows: |
| 77 | + |
| 78 | +``` |
| 79 | +<type>[optional scope]: <description> |
| 80 | +
|
| 81 | +[optional body] |
| 82 | +
|
| 83 | +[optional footer(s)] |
| 84 | +``` |
| 85 | + |
| 86 | +Types: |
| 87 | + |
| 88 | +- `feat`: A new feature |
| 89 | +- `fix`: A bug fix |
| 90 | +- `docs`: Documentation only changes |
| 91 | +- `style`: Changes that do not affect the meaning of the code |
| 92 | +- `refactor`: A code change that neither fixes a bug nor adds a feature |
| 93 | +- `perf`: A code change that improves performance |
| 94 | +- `test`: Adding missing tests or correcting existing tests |
| 95 | +- `build`: Changes that affect the build system or external dependencies |
| 96 | +- `ci`: Changes to our CI configuration files and scripts |
| 97 | +- `chore`: Changes to the build process or auxiliary tools |
| 98 | + |
| 99 | +Examples: |
| 100 | + |
| 101 | +```bash |
| 102 | +git commit -m "feat(engine): add support for custom validators" |
| 103 | +git commit -m "fix(webawesome): resolve styling issues in dark mode" |
| 104 | +git commit -m "docs: update API documentation" |
| 105 | +git commit -m "build: update typescript to 5.8.3" |
| 106 | +git commit -m "ci: add node 21 to test matrix" |
| 107 | +``` |
| 108 | + |
| 109 | +## Submitting a Pull Request |
| 110 | + |
| 111 | +1. Push your changes to your fork: |
| 112 | + |
| 113 | + ```bash |
| 114 | + git push origin feat/your-feature-name |
| 115 | + ``` |
| 116 | + |
| 117 | +2. Go to the original repository on GitHub and create a Pull Request |
| 118 | + |
| 119 | +3. In your PR description: |
| 120 | + |
| 121 | + - Clearly describe the problem and solution |
| 122 | + - Include the relevant issue number if applicable |
| 123 | + - Include screenshots/GIFs for UI changes |
| 124 | + |
| 125 | +4. Wait for the maintainers to review your PR. Make any requested changes. |
| 126 | + |
| 127 | +## Project Structure |
| 128 | + |
| 129 | +``` |
| 130 | +packages/ |
| 131 | + ├── engine/ # Core form engine |
| 132 | + ├── generics/ # Generic utilities, form HTML element and helpers |
| 133 | + ├── webawesome/ # Web components form implementation |
| 134 | + ├── ... |
| 135 | +e2e/ # End-to-end tests |
| 136 | +example-app/ # Example application |
| 137 | +scripts/ # Build and utility scripts |
| 138 | +``` |
| 139 | + |
| 140 | +## Need Help? |
| 141 | + |
| 142 | +If you need help or have questions: |
| 143 | + |
| 144 | +1. Check the documentation |
| 145 | +2. Open an issue with a clear title and description |
| 146 | +3. Be respectful and constructive in all interactions |
| 147 | + |
| 148 | +Thank you for contributing to JSON Schema Form Element! 💖 |
0 commit comments