Skip to content

Latest commit

 

History

History
185 lines (132 loc) · 13.4 KB

CONTRIBUTING.md

File metadata and controls

185 lines (132 loc) · 13.4 KB

Contributing to Clay

Want to contribute to Clay? There are a few things you need to know before you start sending out your pull requests or opening issues.

Here's a set of guidelines to contribute to Clay and its packages. Use your common sense and feel free to propose changes to this document in a pull request.

Table of contents

What should I know before I get started?

Clay and Packages

The Clay repository follows the monorepo approach, all the major components that are the pillars of Clay are here in this repository.

  • clay-css - The pillar to give colors and structure to Clay, containing the CSS and examples of HTML markup of the components.
  • clay-components - All components that follow clay-css marking and Lexicon use cases, developed on Metal.js with Soy (Closure templates) and the new and current components will be rewritten in React in version 3.0.
  • clayui.com - Contains the source code and documentation powering clayui.com.

How can I contribute?

Reporting Bugs

This section guides you to submit an error report to Clay. Following these guidelines helps maintainers understand your report, reproduce the behavior, and find related reports.

Before submitting a bug report

  • Perform a cursory search to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one.

How do I submit a (good) bug report?

Bugs are tracked as Github issues. Create an issue and provide the information you need to help maintainers reproduce the problem:

  • Use a clear and descriptive title for the issue to identify the problem.
  • Describe the exact steps to reproduce the problem in as much detail as possible.
  • Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.
  • Explain which behavior you expected to see instead and why.
  • Include screenshots and animated GIFs if necessary.
  • If the problem is related to performance or memory, include a CPU profile capture with your report.
  • If the problem only occurs in a specific browser describe the version and name of the browser.

Provide more context by answering this question:

  • Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.

Your First Pull Request

If you want to contribute to this project and do not know where to start, issues with the "good first issue" label are a great place to start.

If you decide to fix an issue, please be sure to check the comment thread in case somebody is already working on a fix. If nobody is working on it at the moment, please leave a comment stating that you intend to work on it so other people don’t accidentally duplicate your effort.

Proposing a Change

This section guides you through how to propose a public API change, make non-trivial changes to the implementation, or propose something new. Following these guidelines helps maintainers understand your suggestion and your point of view.

Before submitting a suggestion for improvement

  • Perform a cursory search to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.

How do I submit a suggestion for improvement?

Suggestions for enhancement or API changes are tracked as Github issues. Please create an issue in this repository and provide the following information:

  • Use a clear and descriptive title for the issue to identify the suggestion.
  • Provide a step-by-step description of the suggested enhancement in as much detail as possible.
  • Describe the current behavior and explain which behavior you expected to see instead and why.
  • Provide details of the impact your change will cause and how you will proceed with it.
  • Provide the pros and cons of your change.
  • Provide at least one alternative for your change.

Sending a Pull Request

This section guides you how to send a pull request. The main staff is always monitoring pull requests. Following these guidelines helps the maintainers to do thorough review.

Since Travis is failing on executing a11y tests due to out of date suid you need to execute npm run pa11y locally before sending any PR to verify we're following accessibility standards.

Before sending a pull request

  • Fork the repository and create your branch from develop.
  • Run yarn at the root of the repository for the installation of project dependencies.
  • Run yarn lerna to install the dependencies of each package and link them together.
  • Run yarn build to build all packages.
  • If you’ve fixed a bug or added code that should be tested, add tests!
  • Run yarn test to ensure the test suite passes.
  • If you have modified a Soy file, make sure the related tests passed by running yarn testSoy.
  • Run yarn format to format your code with Prettier.
  • Run yarn lint for make sure your code lints.
  • Run yarn mcritic to follow the rules of Soy.

Styleguides

Git Commit Messages

This section guides you through how to write commit messages in Clay. Following these guidelines helps us maintain order and ease of finding things.

Before you make a confirmation message

  • Make sure that the problem or change you are making already exists.
  • Consider starting the commit message with the word Fixes always following with reference to issue:
    • Fixes #0 - bla bla
    • Fixes #0, #1 - bla bla

JavaScript Styleguide

All JavaScript must adhere to Liferay JavaScript style guide.

Documentation Styleguide

  • Use JSDOC for documentation in your JavaScript code.

Example

/**
 * Data to add to the element.
 * @default undefined
 * @instance
 * @memberof ClayActionsDropdown
 * @type {?object}
 */
data: Config.object()

Additional Notes

Issue Labels

This section lists the labels we use to help us organize and track the issues.

Labels are organized by categories, such as labels that indicate where the problem is, resolution, status...

You may want to use Github search to find groups of issues you are interested in. For example, you may be interested in open issues labeled as bugs, but only in Clay components. Use this to create more focused queries.

Categorization

Category Description
Component The component reflects where the problem is located (e.g Clay Components, Charts...)
Type Reflects issue type (e.g Bug...)
Status Group of labels that reflect the progress of the issue
Resolution Group of labels reflecting resolution of issue
Browser When some issue only affects a specific browser

Labels

Label liferay/clay Category Description
RFC search None Similar to the RFCs that are used in React.js, Ember.js, Gatsby.js and Rust, but to mark issues that are opened as a proposal for changes or to include new things
Infrastructure search Component They are used in issues that are related to monorepo infrastructure, build, process automation...
Clay Components search Component Issues related to Clay components. (e.g ClayCard, ClayLabel...)
Clay Charts search Component Issues related to components of Charts in Soy or React
Generator Clay search Component Issues Related to our Clay Component Generator
Clay CSS search Component Issues related to Clay CSS
Documentation search Component Issues related to documentation in general, in clayui.com or elsewhere...
Accessibility search Component Issues related to accessibility in general
Clay site search Component Issues related to website infrastructure or other things outside the documentation
IE search Browser Issues that happen specifically in IE browser
Chrome search Browser Issues that happen specifically in Chrome browser
Safari search Browser Issues that happen specifically in Safari browser
Firefox search Browser Issues that happen specifically in Firefox browser
Breaking Change search Type Issues that caused some breaking change, whether in API or behavior change...
Bug search Type Issues reporting problems with Component behavior
Epic search Type Issues that are opened as an Epic (a collection of many related things to be done)
Discussion search Type Issues for discussion of some change or to gather information
Enhancement search Type Issues for bringing improvements or refinement of code
Feature Request search Type Issues about adding new features
Regression search Type Issues about regressions
Blocked search Status Issues that are being blocked by other tasks
Help Wanted search Status Issues that are in need of some help
Next Release search Status Issues that will enter into the next release
Duplicate search Resolution Issues that are duplicates
Wontfix search Resolution Issues that will no longer be worked on