feat: changelog and commit linting: adds changelog scripts, commit message linter and updates readmes

.commitlintrc.json

@@ -0,0 +1,3 @@
+{
+    "extends": ["@commitlint/config-conventional"]
+}

.husky/pre-commit

@@ -2,3 +2,5 @@
 . "$(dirname "$0")/_/husky.sh"
 
 yarn lint-staged
+
+npx --no-install commitlint --edit "$1"

.npmignore

@@ -21,6 +21,8 @@ yarn-error.log*
 
 .eslintignore
 .eslintrc.js
+.commitlintrc.json
+.prettierrc.js
 .DS_Store
 .env.development.local
 .env.local

.versionrc.json

@@ -0,0 +1,14 @@
+{
+    "types": [
+        { "type": "feat", "section": "Features" },
+        { "type": "fix", "section": "Bug Fixes" },
+        { "type": "chore", "hidden": true },
+        { "type": "docs", "hidden": true },
+        { "type": "style", "hidden": true },
+        { "type": "refactor", "hidden": true },
+        { "type": "perf", "hidden": true },
+        { "type": "test", "hidden": true }
+    ],
+    "commitUrlFormat": "https://github.com/EightfoldAI/octuple/commits/{{hash}}",
+    "compareUrlFormat": "https://github.com/EightfoldAI/octuple/compare/{{previousTag}}...{{currentTag}}"
+}

CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.

README.md

@@ -3,47 +3,51 @@
 ## About
 
 Octuple creates a shared language and visual consistency across different pages and channels.
+It represents a collection of assets, utilities, and React components for building web applications.
 
 -   Design (and development) work can be created and replicated quickly and at scale.
 -   Alleviates strain on design resources to focus on larger, more complex problems.
 -   Creates a unified language within and between crossfunctional teams.
 -   Creates visual consistency across products, channels, and (potentially siloed) departments.
 -   Serves as an educational tool and reference for junior-level designers and content contributors.
 
-## Prerequisites
+## Changelog
 
--   Install the following:
+You can view the complete list of additions, fixes, and changes in the [change log](./CHANGELOG.md)
 
--   [Git](https://git-scm.com/)
--   [Node](https://nodejs.org/en/download/)
--   [Yarn](https://yarnpkg.com/getting-started/install)
--   [NVM (optional to quickly use different versions of Node)](https://github.com/nvm-sh/nvm)
+## Usage
 
-## Available Scripts
+To use Octuple in your project run the following command:
 
-from the project root folder, you can run:
+Yarn
 
-### `yarn storybook`
+```
+yarn add @eightfold.ai/octuple
+```
 
-Runs the app in the development mode.\
-Open [http://localhost:2022](http://localhost:2022) to view it in the browser.
+NPM
 
-The page will reload if you make edits.\
-You will also see any lint errors in the console.
+```
+npm install @eightfold.ai/octuple
+```
 
-### `yarn build-storybook`
+## How can I contribute?
 
-Builds the Octuple Design System Storybook project for deployment to the `dist` folder.\
+There are many ways to contribute to the Octuple project. Review the following sections to find out which one is right for you.
 
-### `yarn test`
+### Reporting bugs and suggesting enhancements using Eightfold's apps and services
 
-Runs the UTs.\
+Please use the 'Get Help' tool at the bottom of any screen to submit bugs and suggestions.
 
-### `yarn`
+![Get Help](./public/assets/GetHelp.png)
 
-Builds the Octuple Design System Component Library for prod publishing to NPM in to the `lib` folder.\
-Should also run the UTs as part of the process.
-Your package is ready to be published!
+### Create an issue on GitHub
+
+![New Issue](./public/assets/NewIssue.png)
+
+### Pull requests
+
+Review the guidance for pull requests and the contribution workflow in our [contributor guide](./src/CONTRIBUTING.md).
 
 ## License
 

package.json

@@ -15,7 +15,11 @@
         "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
         "format": "prettier --write \"**/*.+(js|jsx|ts|tsx|json|css|scss|md)\"",
         "postinstall": "husky install",
-        "lint-staged": "lint-staged"
+        "lint-staged": "lint-staged",
+        "release": "standard-version",
+        "release:minor": "standard-version --release-as minor",
+        "release:patch": "standard-version --release-as patch",
+        "release:major": "standard-version --release-as major"
     },
     "eslintConfig": {
         "extends": [
@@ -50,6 +54,8 @@
     "devDependencies": {
         "@babel/core": "7.17.5",
         "@babel/runtime": "7.17.2",
+        "@commitlint/cli": "16.2.3",
+        "@commitlint/config-conventional": "16.2.1",
         "@pmmmwh/react-refresh-webpack-plugin": "0.5.3",
         "@storybook/addon-actions": "6.5.0-alpha.47",
         "@storybook/addon-docs": "6.5.0-alpha.47",
@@ -129,6 +135,7 @@
         "sass-loader": "12.3.0",
         "semver": "7.3.5",
         "source-map-loader": "3.0.0",
+        "standard-version": "9.3.2",
         "storybook-addon-state": "1.0.3",
         "style-loader": "3.3.1",
         "terser-webpack-plugin": "5.2.5",
@@ -205,12 +212,10 @@
     },
     "lint-staged": {
         "*.+(js|jsx|ts|tsx)": [
-            "eslint --fix",
-            "git add"
+            "eslint --fix"
         ],
         "*.+(js|jsx|ts|tsx|json|css|scss|md)": [
-            "prettier --write",
-            "git add"
+            "prettier --write"
         ]
     }
 }

src/CONTRIBUTING.md

@@ -0,0 +1,165 @@
+# Eightfold Octuple Design System Component Library
+
+## Prerequisites
+
+-   Install the following:
+
+-   [Git](https://git-scm.com/)
+-   [Node](https://nodejs.org/en/download/)
+-   [Yarn](https://yarnpkg.com/getting-started/install)
+-   [NVM (optional to quickly use different versions of Node)](https://github.com/nvm-sh/nvm)
+
+## Available Scripts
+
+from the project root folder, you can run:
+
+### `yarn storybook`
+
+Runs the app in the development mode.
+Open [http://localhost:2022](http://localhost:2022) to view it in the browser.
+
+The page will reload if you make edits.
+You will also see any lint errors in the console.
+
+### `yarn build-storybook`
+
+Builds the Octuple Design System Storybook project for deployment to the `dist` folder.
+
+### `yarn test`
+
+Runs the UTs.
+
+### `yarn`
+
+Builds the Octuple Design System Component Library for prod publishing to NPM in to the `lib` folder.
+Should also run the UTs as part of the process.
+Your package is ready to be published!
+
+## Contributing
+
+### Setting up your local Git repository
+
+This section describes the steps to set up a Git repository on your local machine, with the intent to contribute to the Eightfold Octuple project. Contributors may use a locally cloned repository to add new components, utilities, do major edits on existing components, or change assets.
+
+One-time setup activities to start contributing:
+
+-   Fork the [Octuple repository](https://github.com/EightfoldAI/octuple) to your GitHub account
+-   Choose a local folder for the cloned files
+-   Clone the repository to your local machine
+-   Configure the upstream remote value
+
+### Overview
+
+To contribute to Eightfold's Octuple project, you can make and edit assets, utilities, and components by cloning the [Octuple repository](https://github.com/EightfoldAI/octuple). Eightfold requires you to fork the [Octuple repository](https://github.com/EightfoldAI/octuple) into your own GitHub account so that you have read/write permissions there to store your proposed changes. Then you use pull requests to merge changes into the read-only central shared repository.
+
+![Repository first time setup](../public/assets/git-and-github-initial-setup.png)
+
+### Fork the repository
+
+Using the appropriate repository, create a fork of the repository into your own GitHub account by using the GitHub website.
+
+A personal fork is required since the main repositorty provides read-only access. To make changes, you must submit a pull request from your fork into the main repository. To facilitate this process, you first need your own copy of the repository, in which you have write access. A GitHub fork serves that purpose.
+
+1. Go to the main repository's GitHub page and click the Fork button on the upper right.
+
+    ![Fork the Octuple repository](../public/assets/fork.png)
+
+2. If you are prompted, select your GitHub account tile as the destination where the fork should be created. This prompt creates a copy of the repository within your GitHub account, known as a fork.
+
+### Choose a local folder
+
+Make a local folder to hold a copy of the repository locally. Choose a location with available disk space.
+
+1. Choose a folder name should be easy for you to remember and type. For example, consider a root folder `C:\source\`
+
+2. Launch Git Bash, PowerShell (Windows) or Terminal (Mac OS) and Change directory (cd) into the folder that you created for hosting the repository locally. Note that Git Bash and Terminal use the Linux convention of forward-slashes instead of back-slashes for folder paths. For example, `cd /c/docs/` or `cd ~/Documents/docs/`
+
+### Create a local clone
+
+Using command line interface, prepare to run the clone command to pull a copy of a repository (your fork) down to your device on the current directory.
+
+1. Run the clone command, by providing the repository name. Cloning downloads (clone) the forked repository on your local computer.
+
+Be sure to specify the path to your fork during the cloning process, not the main repository from which you created the fork. Otherwise, you cannot contribute changes. Your fork is referenced through your personal GitHub user account, such as `github.com/<github-username>/<repo>`.
+
+```
+git clone https://github.com/<github-username>/<repo>.git
+```
+
+Your clone command should look similar to this example:
+
+```
+git clone https://github.com/imadev/octuple.git
+```
+
+2. When you're prompted, enter your GitHub credentials and two-factor authentication code.
+
+3. The clone command runs and downloads a copy of the Octuple repository files from your fork into a new folder on the local disk. A new folder is made within the current folder. It may take a few minutes, depending on the repository size. You can explore the folder to see the structure once it is finished.
+
+### Configure remote upstream
+
+After cloning the repository, set up a read-only remote connection to the main repository named upstream. You use the upstream URL to keep your local repository in sync with the latest changes made by others. The git remote command is used to set the configuration value. You use the fetch command to refresh the branch info from the upstream repository.
+
+1. If you're using Git Credential Manager, use the following commands.
+
+```
+cd <repo>
+git remote add upstream https://github.com/EightfoldAI/octuple.git
+git fetch upstream
+```
+
+2. View the configured values and confirm the URLs are correct. Ensure the origin URLs point to your personal fork. Ensure the upstream URLs point to the main repository.
+
+```
+git remote -v
+```
+
+Example remote output is shown. A fictitious git account named MyGitAccount is configured with a personal access token to access the Octuple repo:
+
+```
+origin  https://github.com/MyGitAccount/octuple.git (fetch)
+origin  https://github.com/MyGitAccount/octuple.git (push)
+upstream        https://github.com/EightfoldAI/octuple.git (fetch)
+upstream        https://github.com/EightfoldAI/octuple.git (push)
+```
+
+3. If you made a mistake, you can remove the remote value. To remove the upstream value, run the command `git remote remove upstream`.
+
+### Component code style guide
+
+The Octuple project provides evolving guidelines. To learn more about how to create new, or edit existing components read [COMPONENTS.md](./components/COMPONENTS.md)
+
+### Commits
+
+When committing changes the Octuple project lints commit messages using the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0-beta.2/). The subject line `<description>` must not be sentence-case, start-case, pascal-case, upper-case and must contain one of the following key words representing the `<type>` of commit: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test. The subject line: `<type>[optional scope]: <description>` must not be greater than 100 characters. The combined `[optional body]` and `[optional footer]` must not be greater than 100 characters.
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer]
+```
+
+An example of such a message:
+
+```
+fix: ABC-123: button not keyboard accessible
+
+The button component had a tabIndex of -1 by default
+and therefore it was not keyboard accessible
+```
+
+### Pull requests
+
+A pull request provides a convenient way for a contributor to propose a set of changes that will be applied to the upstream repo's main branch. The changes (also known as commits) are stored in a contributor's downstream repo branch, so GitHub can first model the impact of merging them into the main branch. A pull request also serves as a mechanism to provide the contributor with feedback from a build/validation process, the pull request reviewer, to resolve potential issues or questions before the changes are merged into the main branch.
+
+To learn more please read:
+
+-   [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow)
+-   [Creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
+-   [Creating a pull request from a fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+
+## License
+
+MIT (c) 2022 Eightfold