📝(doc) update docs to install published packages + contributing guide

Updated various parts of existing documentations to make a clean path to learn how to install the library. I let the most complicated part in the tokens's README.md file, which is referenced from the Storybook.
2023-01-30 15:00:46 +01:00
parent 4ebbf168e2
commit 63118d0f3e
5 changed files with 1216 additions and 741 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,80 @@
+# Contributing to Cunningham
+
+Want to contribute to Cunningham? We got you covered.
+
+We try to raise our code quality standards and expect contributors to follow
+the recommandations from our [handbook](https://handbook.openfun.fr/).
+
+## Development
+
+### First start
+
+Install and build packages
+
+```
+make bootstrap
+```
+
+And then run dev servers
+
+```
+make dev
+```
+
+Then, you will be able to access the demo app on [http://localhost:3200](http://localhost:3200) and the React components package's Storybook on
+[http://localhost:6006](http://localhost:6006)
+
+### Building
+
+In order to build all packages of this repo you just need to type the following command at the root of the monorepo.
+
+```
+make build
+```
+
+## Sending a pull request
+
+When submitting please follow those steps:
+
+- Make sure you followed the commit conventions from the [handbook/git](https://handbook.openfun.fr/git).
+- Make sure that you added tests covering your changes.
+- Run `make deploy` to tests, lint and build the project.
+- Create a [changeset](#adding-a-changeset) by running `yarn changeset` at the root of the repo. In any case, a bot will verify if your PR contains a changeset.
+
+### Changelog
+
+The changelog is created with [Changesets](https://github.com/changesets/changesets).
+
+#### Adding a changeset
+
+A changeset describes changes made in a branch or commit. It holds three bits of information:
+
+- What packages we need to release
+- What version we are releasing packages
+- A changelog entry for the released packages
+
+Add a changeset if you have made any changes that will require a package version bump and release:
+
+1. Run `yarn changeset`.
+2. Select the packages you want to include using ↑ and ↓ to navigate to packages, and space to select a package. Hit enter when all desired packages are selected.
+3. Select a [bump type](https://semver.org/) for each selected package.
+4. Provide a message to be written into the changelog on the next release.
+
+#### Writing a changelog message
+
+Keep the following in mind when authoring your changelog entry (final prompt after running `yarn changeset`):
+
+- Begin sentences with explicit verbs like "add", "fix", "refactor"
+- Avoid redundancy when possible
+- Use sentence case
+- Use plain language
+
+#### Out of scope for the changelog
+
+Generally, changes related to these topics can be omitted:
+
+- Doc typo fixes
+- Dev dependencies upgrades
+- Chores (infrastructure, release process…)
+
+This part of the documentation is 99% inspired by [Polaris](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#adding-a-changeset)
--- a/README.md
+++ b/README.md
@@ -1,53 +1,20 @@
-# Cunningham, the best OpenSource Design System
+# 🎨 Cunningham, the best OpenSource Design System

 [![CircleCI](https://circleci.com/gh/openfun/cunningham/tree/master.svg?style=svg)](https://circleci.com/gh/openfun/richie/tree/master)

 <p align="center">
-    <a href="https://openfun.github.io/cunningham"><b>Documentation</b></a> •
-    <a href="https://www.figma.com/file/sSEMhow3g5zpEkyDLEQ1ZO/DS-Cunningham?node-id=47%3A261&t=nKRnadK4sslyVxD7-0"><b>Figma</b></a>
+    <a href="https://openfun.github.io/cunningham"><b>📚&nbsp;&nbsp;Documentation</b></a> •
+    <a href="https://www.figma.com/file/sSEMhow3g5zpEkyDLEQ1ZO/DS-Cunningham?node-id=47%3A261&t=nKRnadK4sslyVxD7-0"><b>🖌️&nbsp;&nbsp;Figma</b></a>
 </p>


 ## Getting started

-Packages are not published yet, but once it is done we will show people how to install packages.
-
-## Development
-
-### First start
-
-Install and build packages 
-
-```
-make bootstrap
-```
-
-And then run dev servers
-
-```
-make dev
-```
-
-Then, you will be able to access the demo app on `http://localhost:3200` and the React components package's Storybook on
-`http://localhost:6006`
-
-### Building
-
-In order to build all packages of this repo you just need to type the following command at the root of the monorepo. 
-
-```
-make build
-```
+Everything is detailed on our [documentation](https://openfun.github.io/cunningham). 📚

 ## Contributing

-This project is intended to be community-driven, so please, do not hesitate to
-get in touch if you have any question related to our implementation or design
-decisions.
-
-We try to raise our code quality standards and expect contributors to follow
-the recommandations from our
-[handbook](https://openfun.gitbooks.io/handbook/content).
+Please see our [contributing guidelines](./CONTRIBUTING.md).

 ## License

--- a/packages/react/.storybook/preview.js
+++ b/packages/react/.storybook/preview.js
@@ -11,6 +11,7 @@ export const parameters = {
  options: {
    storySort: (a, b) => {
      const roots = ['Getting Started', 'Components'];
+      const gettingStartedOrder = ['Installation', 'Colors', 'Spacings', 'Typography'];

      const aParts = a.title.split('/');
      const bParts = b.title.split('/');
@@ -18,6 +19,9 @@ export const parameters = {
        return roots.indexOf(aParts[0]) - roots.indexOf(bParts[0]);
      }
      if (aParts[1] !== bParts[1]) {
+        if (aParts[0] === 'Getting Started') {
+          return gettingStartedOrder.indexOf(aParts[1]) - gettingStartedOrder.indexOf(bParts[1]);
+        }
        return aParts[1].localeCompare(bParts[1]);
      }
      return 0;
--- a/packages/react/src/docs/installation.stories.mdx
+++ b/packages/react/src/docs/installation.stories.mdx
@@ -0,0 +1,67 @@
+import { Canvas, Meta, Story, Source, ArgsTable } from '@storybook/addon-docs';
+
+<Meta title="Getting Started/Installation"/>
+
+# Installation
+
+First, install the library
+
+<Source
+  language='bash'
+  dark
+  format={false}
+  code={`
+  yarn add @openfun/cunningham-react
+  `}
+/>
+
+Then, add this script to your `package.json` file
+
+<Source
+  language='json'
+  dark
+  format={false}
+  code={`
+{
+  "scripts": {
+    "build-theme": "cunningham -g css -o src"
+  },
+}
+`}
+/>
+
+> Please take a look at [tokens documentation](https://github.com/openfun/cunningham/tree/main/packages/tokens#configuration-file) for more informations about the `cunningham` command line tool and to customize your local theme.
+
+Then, in order to generate the css file, run
+
+<Source
+  language='bash'
+  dark
+  format={false}
+  code={`
+  yarn build-theme
+  `}
+/>
+
+It will generate a file named `cunningham-tokens.css`.
+
+Then, add these lines at the top of your main stylesheet file:
+
+
+<Source
+  language='css'
+  dark
+  format={false}
+  code={`
+@import "@openfun/cunningham-react/style"; // Imports the default theme.
+@import "cunningham-tokens"; // Imports the file you just generated.
+  `}
+/>
+
+> Please see [here](https://github.com/openfun/cunningham/tree/main/packages/tokens#use-the-design-tokens) to see how to use the design tokens in your source code.
+
+We're done! 🎉
+
+Now to verify that everything works well by trying to render a component, like the [Button](?path=/story/components-button-doc--page) for example.
+
+
--- a/yarn.lock
+++ b/yarn.lock