CONTRIBUTING.md

Contribute to Lattice

Hi! First of all, thanks for taking some time to make a contribution to the project. Below you will find all the basic information to get started.

Table of Contents

• Setting Up a Local Copy
• Customized React Scripts
• Development
• Working in a specific latticejs module
• How to run a demo app
• How To Consume a Local Package
• Troubleshooting
• Cleaning the project
• Solving greenkeeper issues

Setting Up a Local Copy

1. Clone the repo with git clone https://github.com/latticejs/lattice.

2. If is not already present, install yarn globally npm i -g yarn.

3. Run yarn in the root lattice folder.

4. Finally, run yarn run lerna run prepublish in order to trigger npm install lifecycle (see more)

Once it is done, you can modify any file locally and run yarn start, yarn test or yarn build just like in a generated project.

Running our Customized React Scripts

If you want to try out the @latticejs/react-scripts locally, you can run this command on the root lattice folder:

yarn run create-react-app test-demo-app
cd test-demo-app

and then run yarn start or yarn build.

Development

Creating Lattice packages

Readme

New packages must have a README.md file with at least the next main sections:

• Package name and description.
• Install: How to install this package.
• Usage: How to import/run/use this package.
  • Example: Brief example (some code) showing the basics of your package.
  • API: Package settings, methods and configuration.
• FAQs If any. Some troubleshooting is welcome.

Storybook

If your package includes some component, you can include a Storybook to show different usage ways (based on state, props, settings) of the component.

Install

Here is a basic start guide with help about installing, configuring and running Storybook.

Addons

Storybook comes with a set of Addons wich can be very usefull to enhance your components stories.

Some of them:

• Actions: Log and inspect events of your component.
• Readme: Adds a readme section.
• Notes: Notes tab with support for HTML.

Check out the Addons full list.

Tests

Include tests for your package.

1. Create a test/ folder into your package with all your tests files.
2. Add a test npm script in your package.json file.

Example:

package.json

    ...
    "scripts": {
-        "start": "node index.js"
+        "start": "node index.js",
+        "test": "jest"
    },
    ...

We are currently using two main testing tools (can be used together if needed):

• Enzyme: (only for React) Test tool for components output.
• Jest: Testing toolset. It can be used even to test non-web packages or libraries.

Working in a specific latticejs module

1. Run cd pacakges/<module>
2. Development using storybook: yarn storybook

How to run a demo app

1. Run npx create-react-app test-demo-app outside project's workspace.

2. Remove node_modules directory from the recently created react app test-demo-app

3. Move test-demo-app inside lattice/packages directory.

4. Run yarn in the root lattice folder.

5. Finally, cd test-demo-app && yarn start.

How to consume a local package

1. For example, inside test-demo-app directory you can run npx lerna add @lattice/target-module --scope=test-demo-app

scope should be the name defined in local package.json.

2. If target module has peer dependencies, those should be installed as mentioned in 1.

Now modules are linked and local changes can be seen instantly.

Troubleshooting

Cleaning the project

Sometimes, after a major change in the source is preferable start with a new clean repository: git clean -xdf

Remember that you are going to lose your unversioned files.

Solving Greenkeeper issues

Sometimes greenkeeper PRs fails for some reason and you can't immediately merge. When that happens we usually check the following steps:

1. Check Travis output. Usually there, you would see what is happening. A common error is having 'different snapshots'.
2. Review changes proposed by greenkeeper (GK). Check the changelog of the involved libraries/modules.
3. Clone the GK branch.
4. Fix the error.
   1. If the error is 'different snapshots' you should re-generate the snapshots locally, cd into the package dir, then run yarn test -u
   2. Repeat this process if necessary.
   3. Commit your changes.
5. When you think that everything is working again. Run the global storybook command: yarn storybook at root level. This will help you see that all the components are working OK.
6. Push your changes.
7. Now checks should pass and you will be able to merge.