CONTRIBUTING.md

Contributing

Thank you for reaching the contribution page and showing the true gremlin in you! In Grommet we do believe that the more the merrier – Welcome! Thank you for making this step of joining and contributing to our community, and for helping us make Grommet the best tool for streamlining the way you develop apps. You came to the right place to start your contribution! Follow the guidelines and let us know if we can help with anything else.

Grommet Projects

Grommet is divided into several projects, the following are notable:

• grommet – the primary Grommet 2.X project is actively developed and contributions are more than welcome! Be sure to check the good first issues.
• grommet-icons – iconography for Grommet and React.js.
• react-desc – add a schema to your React components based on React PropTypes.
• design-kit – the Grommet Design Kit provides a set of sticker sheets and templates to help bootstrap your design process.

You can Become a Contributor

Afterall, that’s why you’re here, right? Quick steps and ideas of how you can contribute to Grommet:

1. Code, code, code… (and make a Pull Request).
2. Create design assets or style guide revisions.
3. Submit updates and improvements to the documentation.
4. Submit articles and guides which are also part of the documentation.
5. Join the Slack community to interact with and help Grommet users.
6. Help a Grommet designer or developer by answering questions on Stack Overflow, Slack, or GitHub.
7. Report bugs and propose new features by filing issues on GitHub, or come talk to us and fellow contributors in our Slack community about your issue or idea.
8. Share with us exciting projects using Grommet in our Slack community.

How to Contribute

The best way to collaborate with the project contributors is through the Grommet organization on GitHub: https://github.com/grommet.

You are invited to contribute new features, fixes, or updates – large or small. We are always thrilled to receive pull requests, and do our best to process them as fast as we can.

Before you start to code, we recommend discussing your plans through a GitHub issue, especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give you feedback on your design, and help you find out if someone else is working on the same thing.

• If you want to contribute design assets or style guide revisions, please open a GitHub pull request or open a GitHub issue against the design-kit project.
• If you want to raise an issue such as a defect or an enhancement request, please open a GitHub issue for the appropriate project. Please keep the following in mind:
  • Try to reduce your code to the bare minimum required to reproduce the issue.
  • If we can’t reproduce the issue, we can’t fix it. Please list the exact steps required to reproduce the issue.

We review issues and pull requests on a weekly basis (sometimes more frequently). When we require more information from you, we’ll ask. In order to keep the issue and pull request queue clean, we ask that you respond within one week or we’ll close the issue pending your response.

After an issue is created or a pull request is submitted, contributors and/or maintainers will offer feedback. If the pull request passes review, a maintainer will accept it with a comment.

When a pull request for code contribution fails testing, the author is expected to update the pull request to address the failure(s) until it passes testing and the pull request can merge cleanly.

At least one review from a maintainer is required for all patches.

Developer’s Certificate of Origin

All contributions must include acceptance of the DCO:

Developer Certificate of Origin Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors. 660 York Street, Suite 102, San Francisco, CA 94110 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

(b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

(d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

Sign Your Work

To accept the DCO, simply add this line to each commit message with your name and email address (git commit -s will do this for you):

Signed-off-by: Jane Example <[email protected]>

For legal reasons, no anonymous or pseudonymous contributions are accepted.

Design Contributions

The Grommet community values contributions on the design side of the project. The Grommet style guide and designer assets are open for contributions just as the development platform is. You may either submit an issue on GitHub with a detailed recommendation, or open a pull request with the updated assets. Please open a GitHub pull request or open a GitHub issue against the grommet-design project.

Submitting Code Pull Requests

We encourage and support contributions from the community. No fix is too small. We strive to process all pull requests as soon as possible and with constructive feedback. If your pull request is not accepted at first, please try again after addressing the feedback you receive.

To make a pull request you will need a GitHub account. For help, see GitHub’s documentation on forking and pull requests.

Development happens on the master branch. In order for you to get started you should:

1. fork the grommet repository
2. clone it git clone https://github.com/<your-username>/grommet.git
3. install dependencies using: yarn install

The components code lives in src/js/components. The structure of the project is a bit particular since it is using lots of internal tooling to try to produce up-to-date documentation and minimise bugs. A few gotchas you may run into while contributing could include:

• The read-me files in the components are auto-generated. You won’t need to update them. A big chunk of the documentation and prop-type validation is happening via the doc.js files.
• Code coverage and unit-testing is an important process of development. A pre-commit hook exists which runs the test suite and aborts the commit if any fail. To manually run tests, you should run yarn test. If you need to update snapshots then run yarn test-update.
• If you would like to use your development branch in a local project for testing and debugging purposes, this guide shares steps to link local projects.
• We are actively working on providing a seamless TypeScript experience. Don’t forget to update corresponding index.d.ts files.
• For code syntax alignment in your pull request, use prettier.
• Pull requests with code should include tests that validate the changes.

We review issues and pull requests on a weekly basis (sometimes more frequently). If you feel we missed yours don’t hesitate to ping us on Slack!

Testing Your Code

• You can test your code locally along with your changes using: yarn storybook or npm run storybook. This will open the storybook in your browser .

Contributing to the Documentation

Grommet uses an internal tool for most of its documentation. If you are looking to modify component documentation then you only need to have a look at the doc.js files.

These files are used to generate the documentation on the Grommet website. That code lives in the grommet-site repository.

Found an error in the documentation? File an issue.

Need More Help?

Watch this video to learn how to contribute to Grommet. The GitHub contribution workflow is a bit complex and we want to make sure we don’t lose your valuable contributions because of that. Note that the video is outdated and talks about contributing to Grommet 1.X, but it may still be helpful for new users.

References

This contribution guide was inspired by the contribution guides for Grunt, CloudSlang, and Docker Library.