|
| 1 | +# Contributing to Lit |
| 2 | + |
| 3 | +Thank you for your interest in contributing to Lit! |
| 4 | + |
| 5 | +There are many ways to contribute to the Lit project, and we have many different needs to be addressed. All contributions, from PRs to reports of successful usage, are appreciated and valuable. |
| 6 | + |
| 7 | +## Code of Conduct |
| 8 | + |
| 9 | +We have a [Code of Conduct](https://github.com/lit/lit/blob/main/CODE_OF_CONDUCT.md), please follow it in all interactions with project maintainers and fellow users. |
| 10 | + |
| 11 | +## Set up |
| 12 | + |
| 13 | +```bash |
| 14 | +git clone https://github.com/lit/lit.dev.git |
| 15 | +cd lit.dev |
| 16 | +npm ci |
| 17 | +npm run dev |
| 18 | +``` |
| 19 | + |
| 20 | +## Tests |
| 21 | + |
| 22 | +### Run the suite of tests |
| 23 | + |
| 24 | +1. `npm test` |
| 25 | + |
| 26 | +Note, all screenshot tests will fail locally. This is because the goldens are generated specifically from the linux instance run by GitHub Actions. To update the goldens you must: |
| 27 | + |
| 28 | +- Wait for GitHub Actions to run the tests |
| 29 | +- Click on the failing test action |
| 30 | +- Click on the "summary" button on the left panel |
| 31 | +- Download the new goldens from the "Artifacts" section |
| 32 | +- Update the goldens locally |
| 33 | +- Upload your PR with the new goldens |
| 34 | + |
| 35 | +## Tutorial Contributions |
| 36 | + |
| 37 | +See the Tutorial Contributing guide at [packages/lit-dev-content/samples/tutorials/CONTRIBUTING.md](./packages/lit-dev-content/samples/tutorials/CONTRIBUTING.md) |
| 38 | + |
| 39 | +## Filing Issues |
| 40 | + |
| 41 | +Issues are one of the most important ways to contribute to Lit. |
| 42 | + |
| 43 | +Please search though open and closed issues to see if a similar issue already exists. If not, open an issue and try to provide a minimal reproduction if you can. |
| 44 | + |
| 45 | +Occasionally we'll close issues if they appear stale or are too vague - please don't take this personally! Please feel free to re-open issues we've closed if there's something we've missed and they still need to be addressed. |
| 46 | + |
| 47 | +## Pull Requests |
| 48 | + |
| 49 | +Pull requests are greatly appreciated! |
| 50 | + |
| 51 | +Every documentation page on [lit.dev](https://lit.dev) should have an "Edit this page" link at the bottom. That will automatically take you to the GitHub UI to edit that page and submit a Pull Request. This is a great way to contribute to the documentation. |
| 52 | + |
| 53 | +## Code Style |
| 54 | + |
| 55 | +We follow the [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html), but there are a couple of points worth emphasizing: |
| 56 | + |
| 57 | +1. Clear is better than clever. Optimize for simple, readable code first. |
| 58 | +2. Prefer longer, more descriptive names, over shorter names. For most variables, minification means we don't pay for extra characters in production. |
| 59 | +3. Always err on the side of too many comments. When commenting, "why" is more important than "what". |
| 60 | +4. If you're tempted to add a "what" comment, see if you can't restructure the code and use more descriptive names so that the comment is unnecessary. |
| 61 | + |
| 62 | +## TypeScript |
| 63 | + |
| 64 | +We use TypeScript on Lit in order to automatically check the code for type errors and document the types of fields and attributes for easier reading. If you don't know TypeScript, we hope it doesn't discourage you from contributing - TypeScript is a superset of JavaScript that focuses on adding type annotations. |
| 65 | + |
| 66 | +TypeScript is hopefully relatively easy to pick up, but if you have any problems we're more than happy to help. You can submit a pull request with type warnings and we'll either help you fix them, or if you allow commits to your PR branch, fix them for you. VS Code is a very nice IDE for TypeScript development if you care to try it. |
| 67 | + |
| 68 | +## Contributor License Agreement |
| 69 | + |
| 70 | +You might notice our friendly CLA-bot commenting on a pull request you open if you haven't yet signed our CLA. We use the same CLA for all open-source Google projects, so you only have to sign it once. Once you complete the CLA, all your pull-requests will automatically get the `cla: yes` tag. |
| 71 | + |
| 72 | +If you've already signed a CLA but are still getting bothered by the awfully insistent CLA bot, it's possible we don't have your GitHub username or you're using a different email address. Check the [information on your CLA](https://cla.developers.google.com/clas) or see this help article on [setting the email on your git commits](https://help.github.com/articles/setting-your-email-in-git/). |
| 73 | + |
| 74 | +[Complete the CLA](https://cla.developers.google.com/clas) |
0 commit comments