Merge pull request #10 from wpmudev/enhance/documentation

Enhance/documentation
wpmudev · Jan 25, 2021 · 41299a4 · 41299a4
2 parents e3ac3a5 + 5b32983
commit 41299a4
Show file tree

Hide file tree

Showing 5 changed files with 379 additions and 62 deletions.
diff --git a/README.md b/README.md
@@ -1,69 +1,115 @@
-# WPMU DEV Shared UI React Components
-
-## Collaborate
-
-### Initialize
-1. To begin with the project make sure you have **Yarn** and **Lerna** installed on your system.
-2. Run `yarn install` to install all dependencies on the project.
-3. Run `yarn run storybook` to initialize Storybook (project showcase).
-
-### Creating new package/component
-1. Run `npx lerna create {component-name}`.
-2. Follow lerna steps to configure your new package, but make sure to name it correctly: `@wpmudev/react-{component-name}`
-	- **Package name:** `@wpmudev/react-{component-name}`. Notice `@wpmudev/react-` prefix followed by folder name to name your package.
-	- **Version:** `0.0.0`
-	- **Description:** `WPMU DEV Shared UI React {Component Name} Component`
-	- **Keywords:**
-	- **Homepage:**
-	- **License:** GPL-2.0
-	- **Entry Point:** Use default value.
-	- **Git Repository:** Use default value (https://github.com/wpmudev/shared-ui-react.git)
-	- Review and accept changes.
-3. Add React as dev dependency for local testing by running `npx lerna add react --dev --scope=@wpmudev/react-{component-name}`
-4. Add React 16+ as peer dependency for consuming apps by running `npx lerna add [email protected] --peer --scope=@wpmudev/react-{component-name}`
-5. Add **clsx** utility to toggle classes as needed on the components by running `npx lerna add clsx --scope=@wpmudev/react-{component-name}`
-6. Prepare your package for building. Edit your component `package.json` file with the following:
-	- Set `"main": "dist/{component-name}.cjs.js",`
-	- Set `"module": "dist/{component-name}.esm.js",`
-	- Set `"src": "lib/{component-name}.js",`
-	- Add `dist` folder to `files` we are going to pubslih. Ex. `"files": [ "dist", "lib" ]`.
-	- Add builder script `"build": "sui-builder"`.
-	- Add `"publishConfig": { "access": "public" }` to make sure scoped package is going to be publicy viewable.
-
-### Installing npm packages
-
-1. **When required for an specific workspace** simply run `npx lerna add {package-name} --scope=@wpmudev/react-{component-name}`
-2. **When shared between multiple packages** simply run `yarn add -W --dev {package-name}`
-
-## Publishing
-
-**Important:** If you don't want to publish a package/component just include `"private": true` in its `package.json` file.
-
-1. Make builder JS file executable `chmod +x packages/builder/lib/builder.js`.
-2. Build packages `yarn run build`.
-3. Review packages `CHANGELOG.md` files and make sure all changes are listed.
-4. Publish packages `npx lerna publish --no-private`.
-
-If you have a private package that you don't want to publish, you have to specify `"private": true` in `package.json`.
-
-***
-
-### Content to improve
+[![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://opensource.org/licenses/)
+
+# Shared UI Components for React
+
+This is the official implementation of [WPMU DEV Shared UI](https://github.com/wpmudev/shared-ui/) components for React.
+
+## Components
+
+The following is a list of the components that are ready to be used with corresponding links to NPM package and the showcase design spec.
+
+Component | Version
+--- | ---
+[Tutorials List](https://wpmudev.github.io/shared-ui-react/?path=/story/tutorials-list--primary) | [![npm version](https://badge.fury.io/js/%40wpmudev%2Freact-tutorials-list.svg)](https://badge.fury.io/js/%40wpmudev%2Freact-tutorials-list)
+[Tutorials Slider](https://wpmudev.github.io/shared-ui-react/?path=/story/tutorials-slider--primary) | [![npm version](https://badge.fury.io/js/%40wpmudev%2Freact-tutorials-slider.svg)](https://badge.fury.io/js/%40wpmudev%2Freact-tutorials-slider)
+
+## Getting Started
+
+### React Plugins
+
+Go to the component you need, install it using node and start using it on your project.
+
+### Non-React Plugins
+
+#### 1. Install Packages.
+
+Install dependencies for your project:
 
 ```
-# SAMPLE: Add button dependency into shared-ui-react
-npx lerna add @wpmudev/react-button --scope=@wpmudev/shared-ui-react
+npm i react react-dom @babel/core @babel/preset-react --save-dev
+```
+
+#### 2. Babel settings.
+
+Create or edit `.babelrc` file and include the following:
 
-# We are going to use React for the UI components, let's add it as dev dependency first for local testing
-npx lerna add react --dev --scope={component-name}
+```js
+{
+  "presets": [
+    "@babel/preset-env",
+    "@babel/preset-react"
+  ]
+}
+```
+
+#### 3. Webpack settings.
+
+Create or edit `webpack.config.js` file:
+
+```js
+var path = require( 'path' );
+
+var config = {
+  source: {},
+  output: {}
+};
+
+config.source.js          = './assets/js/index.js';
+config.output.jsDirectory = 'assets/js/';
+config.output.jsFileName  = 'index.min.js';
+
+var jsConfig = Object.assign( {}, {
+  entry: config.source.js,
+  module: {
+    rules: [{
+      test: /\.(js|jsx)$/,
+      exclude: /(node_modules|dist)/,
+      use: {
+        loader: 'babel-loader',
+        options: {
+          presets: ['@babel/env']
+        }
+      }
+    }]
+  },
+  resolve: {
+    extensions: ['*', '.js', '.jsx'],
+  },
+  output: {
+    filename: config.output.jsFileName,
+    path: path.resolve( __dirname, config.output.jsDirectory )
+  },
+  devServer: {
+    contentBase: path.resolve( __dirname, '.' )
+  },
+});
+
+module.exports = [ jsConfig ];
+```
 
-# And as a peer dependency using major 16 version for consuming applications
-npx lerna add react --peer --scope={component-name}
+#### 4. Import your component(s).
+
+Create a new file, preferrably inside `/assets/js/` folder, and its name should match the file we are calling from webpack:
+
+```js
+import React from 'react';
+import ReactDOM from 'react-dom';
+
+import {
+  ComponentName
+} from '@wpmudev/react-component-name';
+
+ReactDOM.render(
+  <ComponentName />,
+  document.getElementById( 'app' )
+);
+```
 
-# We are also going to use an utility to toggle classes as needed on the components called "clsx"
-npx lerna add clsx --scope={component-name}
+#### 5. HTML Content.
 
-- - -
+Go to the file where you going to include your component(s), for example: `dashboard.php` file, and add:
 
-npx lerna run build
+```html
+<div id="app"></div>
+<script src="./assets/js/index.min.js"></script><!-- Your react file must be called here -->
 ```
diff --git a/docs/contributions.md b/docs/contributions.md
@@ -0,0 +1,67 @@
+# How to Contribute
+
+If you are looking for a bug to fix, check out [Help Wanted Issues](https://github.com/wpmudev/shared-ui-react/issues?q=is%3Aopen+is%3Aissue+label%3Abug+label%3Aimprovement) on GitHub. Otherwise please open a new issue.
+
+## Working on Issues.
+
+SUI React goal is to convert [Shared UI Library](https://github.com/wpmudev/shared-ui) into React native components. If there is part of the implementation you disagree with please open a [new issue](https://github.com/wpmudev/shared-ui-react/issues/new).
+
+### Add a Feature.
+
+We consider any new API to be a new feature. An API is any of the following:
+
+- Adding a new component
+- Update to React Component APIs
+- Prop updates on React Component
+
+> If changes fall under these categories or you'd like to add a new component please open an [issue](https://github.com/wpmudev/shared-ui-react/issues/new) first.
+
+### Fixing Bugs.
+
+Go ahead an open a pull request when:
+
+- The issue is a small doc change (READMEs, documentation, etc.).
+- The changes you want to perform are under 10 - 20 lines of code.
+
+> Have in mind that anything larger to 20 lines of code or changes to an API will require an issue to be opened first.
+
+## Commit Message Format
+
+The final commit message to the @wpmudev/react-foo package, for GitHub issue 1234, should look like this:
+
+```
+# For a fix to an issue
+🐛 fix/component-name: Short description of fix
+
+# For a new feature
+✨ new/component-name: Short description of feature
+
+# For a doc update
+📝 docs/component-name: Short description of doc changes
+```
+
+This commit message is pulled into our `CHANGELOG` when we release and is based on Angular's Git commit guidelines.
+
+## Pull Requests.
+
+Pull requests should meet the following criteria:
+
+- **PRs should be focused!** PRs should focus on fixing one issue or an additional feature. Anything extra requires another PR.
+- If there is an existing [issue](https://github.com/wpmudev/shared-ui-react/issues/) please refer to it in the description of your PR.
+- Please also add notes/description about what your changes are trying to achieve (or anything you've learned). Brevity appreciated.
+
+### Process
+
+Before opening a PR, it should be up to date with targeted release (`rc<release_number>` ie. `rc0.7.0`, `rc0.8.0`, etc.). In most cases it will never be branched from `master`.
+
+#### Checklist:
+
+- [ ] Lint passes.
+- [ ] Chromatic passes.
+- [ ] Descriptions about your changes.
+
+Once you have passed all checks, the process is as follows:
+
+1. Ping one of the admins ([@iamleigh](https://github.com/iamleigh), [@a-danae](https://github.com/a-danae)) in the PR when its ready for review.
+2. We will either approve, request changes, or explain why we can't accept these changes. And we'll work from there.
+3. Assuming approval, one of the admins will merge your changes and remove the branch from the PR.
diff --git a/docs/guidelines.md b/docs/guidelines.md
@@ -0,0 +1,61 @@
+# General Guidelines
+
+## New Component
+
+```
+npx lerna create foo
+```
+
+Follow lerna steps to configure your new package, but make sure to name it correctly by addinf `@wpmudev/react-` prefix.
+
+```
+$ package name: @wpmudev/react-foo
+$ version (default value):
+$ description: WPMU DEV Shared UI React Foo Component
+$ keywords:
+$ homepage:
+$ license: GPL-3.0
+$ entry point (default value):
+$ git repository (default value):
+```
+
+## Install Packages
+
+Since SUI React is a mono-repo managed by Lerna there are two ways to install packages:
+
+### Global Package
+
+When package is going to be shared between multiple components or going to be used on root.
+
+```
+yarn add -W --dev package-name
+```
+
+### Component Package
+
+When package is required for an specific component.
+
+```
+# Regular dependency
+npx lerna add package-name --scope=@wpmudev/react-foo
+
+# Development dependency
+npx lerna add package-name --dev --scope=@wpmudev/react-foo
+
+# Peer dependency
+npx lerna add package-name --peer --scope=@wpmudev/react-foo
+```
+
+## Showcase
+
+Globally install [Yarn](https://yarnpkg.com/getting-started/install) and [Lerna](https://lerna.js.org/). Since showcase is managed by Storybook run this in the root directory to install Storybook CLI:
+
+```
+npx sb init
+```
+
+Now you can initialize your local environment:
+
+```
+yarn run storybook
+```