chore: Updated README and added a Contributin guide

workleap · Apr 8, 2024 · 60964c6 · 60964c6
1 parent c87261e
commit 60964c6
Show file tree

Hide file tree

Showing 2 changed files with 159 additions and 79 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,151 @@
+# Contributing
+
+The following documentation is only for the maintainers of this repository.
+
+- [Installation](#installation)
+- [Release the package](#release-the-package)
+- [Available commands](#commands)
+- [CI](#ci)
+
+## Installation
+
+This project uses PNPM, therefore, you must [install PNPM](https://pnpm.io/installation) first:
+
+```bash
+npm install -g pnpm
+```
+
+To install this project, open a terminal at the root of the project and execute the following command:
+
+```bash
+pnpm install
+```
+
+### Setup Retype
+
+[Retype](https://retype.com/) is the documentation platform that Squide is using for its documentation. As this project is leveraging a few [Pro features](https://retype.com/pro/) of Retype.
+
+Everything should work fine as-is but there are a few limitations to use Retype Pro features without a wallet with a licence. If you want to circumvent these limitations, you can optionally, setup your [Retype wallet](https://retype.com/guides/cli/#retype-wallet).
+
+To do so, first make sure that you retrieve the Retype license from your Vault (or ask IT).
+
+Then, open a terminal at the root of the project and execute the following command:
+
+```bash
+npx retype wallet --add <your-license-key-here>
+```
+
+## Release the package
+
+When you are ready to release the packages, you must follow the following steps:
+
+1. Run `pnpm changeset` and follow the prompt. For versioning, always follow the [SemVer standard](https://semver.org/).
+2. Commit the newly generated file in your branch and submit a new Pull Request (PR). Changesets will automatically detect the changes and post a message in your pull request telling you that once the PR closes, the versions will be released.
+3. Find someone to review your PR.
+4. Merge the Pull request into `main`. A GitHub action will automatically trigger and update the version of the packages and publish them to [npm](https://www.npmjs.com/). A tag will also be created on GitHub tagging your PR merge commit.
+
+### Troubleshooting
+
+#### Github
+
+Make sure you're Git is clean (No pending changes).
+
+#### NPM
+
+Make sure GitHub Action has **write access** to the selected npm packages.
+
+#### Compilation
+
+If the packages failed to compile, it's easier to debug without executing the full release flow every time. To do so, instead, execute the following command:
+
+```bash
+pnpm build
+```
+
+By default, packages compilation output will be in their respective *dist* directory.
+
+#### Linting errors
+
+If you got linting error, most of the time, they can be fixed automatically using `eslint . --fix`, if not, follow the report provided by `pnpm lint`.
+
+## Commands
+
+From the project root, you have access to many commands. The most important ones are:
+
+#### build
+
+Build the library.
+
+```bash
+pnpm build
+```
+
+#### lint
+
+Lint the files (ESLint, StyleLint and TS types).
+
+```bash
+pnpm lint
+```
+
+### changeset
+
+To use when you want to publish a new package version. Will display a prompt to fill in the information about your new release.
+
+```bash
+pnpm changeset
+```
+
+#### clean
+
+Clean the shell packages and the sample application (delete `dist` folder, clear caches, etc..).
+
+```bash
+pnpm clean
+```
+
+#### reset
+
+Reset the monorepo installation (delete `dist` folders, clear caches, delete `node_modules` folders, etc..).
+
+```bash
+pnpm reset
+```
+
+#### list-outdated-deps
+
+Checks for outdated dependencies. For more information, view [PNPM documentation](https://pnpm.io/cli/outdated).
+
+```bash
+pnpm list-outdated-deps
+```
+
+#### update-outdated-deps
+
+Update outdated dependencies to their latest version. For more information, view [PNPM documentation](https://pnpm.io/cli/update).
+
+```bash
+pnpm update-outdated-deps
+```
+
+## CI
+
+We use [GitHub Actions](https://github.com/features/actions) for this repository.
+
+You can find the configuration in the [.github/workflows](.github/workflows/) folder and the build results are available [here](https://github.com/gsoft-inc/wl-squide/actions).
+
+We currently have 3 builds configured:
+
+### Changesets
+
+This action runs on a push on the `main` branch. If there is a file present in the `.changeset` folder, it will publish the new package version on npm.
+
+### CI
+
+This action will trigger when a commit is done in a PR to `main` or after a push to `main` and will run `build`, `lint-ci` and `test` commands on the source code.
+
+### Retype
+
+This action will trigger when a commit is done in a PR to `main` or after a push to `main`. The action will generate the documentation website into the `retype` branch. This repository [Github Pages](https://github.com/gsoft-inc/wl-web-configs/settings/pages) is configured to automatically deploy the website from the `retype` branch.
+
+If you are having issue with the Retype license, make sure the `RETYPE_API_KEY` Github secret contains a valid Retype license.
diff --git a/README.md b/README.md
@@ -2,94 +2,23 @@
 
 -   [Installation](#installation)
 -   [Usage](#usage)
--   [Available commands](#available-commands)
--   [CI](#ci)
 
 ## Installation
 
-TBD
-
-## Usage
-
-TBD
-
-### Available commands
-
-#### build
-
-Build the library.
-
-```bash
-pnpm build
-```
-
-#### lint
-
-Lint the files (ESLint, StyleLint and TS types).
-
-```bash
-pnpm lint
-```
-
-### changeset
-
-To use when you want to publish a new package version. Will display a prompt to fill in the information about your new release.
-
-```bash
-pnpm changeset
-```
-
-#### clean
-
-Clean the shell packages and the sample application (delete `dist` folder, clear caches, etc..).
+Open a terminal at the root of your project and install the following packages:
 
 ```bash
-pnpm clean
+pnpm add -D @workleap/chromatic-ado
 ```
 
-#### reset
-
-Reset the monorepo installation (delete `dist` folders, clear caches, delete `node_modules` folders, etc..).
-
-```bash
-pnpm reset
-```
-
-#### list-outdated-deps
-
-Checks for outdated dependencies. For more information, view [PNPM documentation](https://pnpm.io/cli/outdated).
-
-```bash
-pnpm list-outdated-deps
-```
-
-#### update-outdated-deps
-
-Update outdated dependencies to their latest version. For more information, view [PNPM documentation](https://pnpm.io/cli/update).
-
-```bash
-pnpm update-outdated-deps
-```
-
-## CI
-
-We use [GitHub Actions](https://github.com/features/actions) for this repository.
-
-You can find the configuration in the [.github/workflows](.github/workflows/) folder and the build results are available [here](https://github.com/gsoft-inc/wl-squide/actions).
-
-We currently have 3 builds configured:
-
-### Changesets
-
-This action runs on a push on the `main` branch. If there is a file present in the `.changeset` folder, it will publish the new package version on npm.
-
-### CI
+## Usage
 
-This action will trigger when a commit is done in a PR to `main` or after a push to `main` and will run `build`, `lint-ci` and `test` commands on the source code.
+TBD
 
-### Retype
+## 🤝 Contributing
 
-This action will trigger when a commit is done in a PR to `main` or after a push to `main`. The action will generate the documentation website into the `retype` branch. This repository [Github Pages](https://github.com/gsoft-inc/wl-web-configs/settings/pages) is configured to automatically deploy the website from the `retype` branch.
+View the [contributor's documentation](./CONTRIBUTING.md).
 
-If you are having issue with the Retype license, make sure the `RETYPE_API_KEY` Github secret contains a valid Retype license.
+## License
 
+Copyright © 2023, Workleap This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/workleap-license/blob/master/LICENSE.