Skip to content

Latest commit

 

History

History
148 lines (99 loc) · 6.36 KB

CONTRIBUTING.md

File metadata and controls

148 lines (99 loc) · 6.36 KB
Raw

Contribution Guidelines

About Crayons

Crayons is a component library based on Web Components. The goal of Crayons is to provide developers with easy to use web components that give apps a Freshworks product like user interface, while reducing the number of lines of code. Crayons is developed using StencilJS that helps build standard-based Web Components.

Crayons Important links

How to Contribute

Crayons has a predefined set of components. As a developer, you not only can use the components in your projects but you can also contribute to Crayons, as it falls under the MIT license. We welcome all contributions, big or small.

Crayons uses monorepo setup. There are 3 packages under packages folder. Uses Lerna for managing monorepo along with npm workspaces.

  1. crayons-core (All core atomic components are present here)
  2. crayons-icons (icon library for crayons)
  3. crayons-i18n (i18n Library for crayons)

Contributing usually requires one or more of the following steps

  1. Forking and setting up
  2. Raising issues towards the repo
  3. Fixing an existing issue
  4. Creating a new component/ changes to other packages

Setup the local environment

Note : Please use npm instead of yarn

only for M* powered Mac

  1. Go to utilities -> Terminal -> Right click and click "get info" and enable "Open using rosetta" which uses x64 arch instead of native arm64 and Use Terminal Rosetta further
  2. Do fresh install of node and NPM as mentioned below and follow other steps

Steps to install

  1. Node Engine requirements
    1. Node: >=14.7.0
    2. NPM: >=7.0.0
  2. Fork the Crayons repository.
  3. Clone your forked Crayons repository. git clone https://github.com/freshworks/crayons
  4. Change directory to the cloned repository and install all the dependencies using npm ci.
  5. Run npm run build to make sure all packages are in sync.
  6. Run git config core.hooksPath .git/hooks/.
  7. To install/uninstall any new dependency for a package , use npm install / uninstall <<dependency>> --workspace=<<packagename>>. You can find the name of the workspace under each package's package.json.
  8. cd packages/crayons-core and npm run start will start the dev server. You can make changes in src/index.html to see live changes in the browser.
  9. npm run test to run the test
  10. To build storybook / docs site, go to root folder and run npm run build. Docs site -> www-dist, Storybook -> docs/storybook-dist
  11. Always run npm run build from root folder before commiting changes so that readme files are in sync.
  12. You can generate a component by running npm run generate in packages/crayons-core directory.
  13. scss variables and mixins are present in styles folder.
Naming Components

When generating components, the custom element tags is prefixed with fw- while the rest of the name is modified to support web component standards. For example, if a component is generated with the name Label, the component that would be generated would be <fw-label/>.

Branches

  1. master - stable release branch
  2. next - experimental pre-release branch (default)

Release Process

To know about the release process check here

Raise an issue

If you find an issue or if you want to raise a feature request in, make sure you raise an issue in https://github.com/freshworks/crayons/issues

Fix an issue

Should you choose to work on a new issue or an existing issue from https://github.com/freshworks/crayons/issues, please follow the steps below.

Prepare the contribution commits

  • Make the required changes to the component.
  • Write integrations tests and unit tests.
  • Check for all lint errors, if there are any fix them.
  • Run tests for all the components.
  • If the component you modify is used in another component make sure you update the tests for that component as well.
  • Raise a Pull Request to the Crayons Repository.

Commit the changes to Github

The Crayons repository uses GitHub's pre-commit hooks. To commit your changes,

  1. Make your changes to the files and add the untracked files to the staging area.

  2. Run git commit.

  3. Choose one of the following based on the nature of your commit.

    Type Description
    feat A new feature
    fix A bug fix
    docs Documentation only changes
    style Changes that do not affect the meaning of the code(white-space, formatting, missing semi-colons, etc)
    refactor A code change that neither fixes a bug nor adds a feature
    perf A code change that improves performance
    test Adding missing tests or correcting existing tests
    build Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
    ci Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
    chore Other changes that don't modify src or test files
    revert Reverts a previous commit

  4. Choose the scope of the change.

    ? What is the scope of this change (e.g. component or file name): (press enter to skip)

  5. Give a brief description for the commit.

    ? Write a short, imperative tense description of the change (max 94 chars):

  6. Give a long description for the commit.

    ? Provide a longer description of the change: (press enter to skip)

  7. Fill in the following details when prompted.

    ? Are there any breaking changes? Yes
? Describe the breaking changes:
documents
? Does this change affect any open issues? No

  8. Give a commit message when prompted.

  9. Run git push -u origin <your-branch>, to push your changes to the forked repo. git hooks will run all the test before pushing the changes. if any test fails, rewrite the tests and ensure that all tests pass before pushing again.

  10. Go to the forked repo in github and raise a PR against next branch. If there are any comments on your PR, address them. Please wait for the PR to be approved.

FAQ

Q: Githooks are not running on my repo. What do I do?

Ans: Please run git config core.hooksPath .git/hooks/ in the root of your project.