chore: reorganise our documentation files into a /docs folder (#1128)

.github/CONTRIBUTING.md

@@ -54,7 +54,7 @@ See example component enabled via feature flags on
 [codesandbox](https://codesandbox.io/s/example-component-canary-olif5).
 
 For more information on how this affects components see
-[CANARY_STRUCTURE.md](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/.github/CANARY_STRUCTURE.md).
+[CANARY_STRUCTURE.md](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/docs/guides/CANARY_STRUCTURE.md).
 
 ## 4. Test your JavaScript code
 

.github/ISSUE_TEMPLATE/component-or-pattern.md

@@ -33,5 +33,5 @@ Before starting work on this epic, please review and complete the following.
 - [ ] Have you reviewed our
       [contribution guidelines](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/.github/CONTRIBUTING.md)?
 - [ ] Have you noted our
-      [reviewer guidelines](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/.github/REVIEWERS_GUIDELINES.md)?
+      [code guidelines](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/docs/CODE_GUIDELINES.md)?
 - [ ] Did you use the CLI to scaffold your new component?

README.md

@@ -1,8 +1,8 @@
 # Carbon for Cloud & Cognitive
 
-> ibm-cloud-cognitive is an open-source implementation of the closed source
+> IBM Cloud & Cognitive is an open-source implementation of the closed source
 > ibm-cloud-cognitive pattern asset library (PAL). These PAL designs build on
-> the foundation of the IBMs open source Carbon Design System and React
+> the foundation of IBM's open source Carbon Design System and React
 > implementation to offer components and patterns beyond the typical component
 > library.
 
@@ -18,17 +18,23 @@
 If you're just getting started and looking to browse our React components, take
 a look at [our Storybook](https://ibm-cloud-cognitive.netlify.app).
 
-This project consists of a number of packages published on npm, see table.
+This project consists of a number of component library packages published on
+npm:
 
-| Package name                                                               | Description                                                                                                       |
-| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| [`@carbon/ibm-cloud-cognitive`](./packages/cloud-cognitive)                | A curated set of components and patterns, built on top of Carbon and designed by the IBM Cloud and Cognitive team |
-| [`@carbon/storybook-addon-theme`](./packages/storybook-addon-carbon-theme) | A storybook addon enabling Carbon theme switching                                                                 |
-| [`@carbon/ibm-cloud-cognitive-cdai`](./packages/cdai)                      | Legacy and non-curated design implementations used in application integration                                     |
-| [`@carbon/ibm-cloud-cognitive-security`](./packages/security)              | Legacy and non-curated design implementations used in security                                                    |
+| Package name                                                  | Description                                                                                                       |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| [`@carbon/ibm-cloud-cognitive`](./packages/cloud-cognitive)   | A curated set of components and patterns, built on top of Carbon and designed by the IBM Cloud and Cognitive team |
+| [`@carbon/ibm-cloud-cognitive-cdai`](./packages/cdai)         | Legacy and non-curated design implementations used in application integration                                     |
+| [`@carbon/ibm-cloud-cognitive-security`](./packages/security) | Legacy and non-curated design implementations used in security                                                    |
 
-The remaining packages are part of our project infrastructure not published on
-npm.
+Also the following additional utility packages are published on npm:
+
+| Package name                                                               | Description                                       |
+| -------------------------------------------------------------------------- | ------------------------------------------------- |
+| [`@carbon/storybook-addon-theme`](./packages/storybook-addon-carbon-theme) | A storybook addon enabling Carbon theme switching |
+
+The remaining packages are part of our project infrastructure and are not
+published on npm.
 
 ## 🙌 Contributing
 

docs/reviews/PR_REVIEW_GUIDELINES.md

@@ -0,0 +1,28 @@
+# PR reviews
+
+When reviewing a PR, check that our
+[code guidelines](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/docs/CODE_GUIDELINES.md)
+are followed, and keep an eye on the
+[release review guidelines](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/docs/reviews/RELEASE_REVIEW_GUIDELINES.md).
+
+Each PR should be reviewed based on these criteria where applicable.
+
+## New production dependencies
+
+If a PR introduces new dependencies in `package.json`, paste the following
+checklist into the PR as a comment and check the items off before approving.
+
+**Tip** You should be able to copy and paste the section below directly into a
+GitHub comment, then check where criteria passed, strike out where not
+applicable.
+
+`## Review of dependencies`
+
+`- [ ]` Verify the dependency has previously been
+[pedigree reviewed](https://pedigree-service.wdc1a.cirrus.ibm.com)\
+`- [ ]` Verify the dependency [doesn't contain any vulnerabilities](https://snyk.io/vuln)\
+`- [ ]` Verify the dependency [bundle size](https://bundlephobia.com) is
+acceptable\
+`- [ ]` Verify the dependency is [actively maintained](https://www.npmtrends.com)\
+`- [ ]` Verify license conditions are met e.g. forwarding of copyright if
+necessary.

.github/REVIEWERS_GUIDELINES.md → docs/reviews/RELEASE_REVIEW_GUIDELINES.md

@@ -1,32 +1,4 @@
-# Review Checklists
-
-## PR reviews
-
-When reviewing a PR, check that our
-[code guidelines](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/.github/CONTRIBUTING.md)
-are followed, and keep an eye on the component review checklist below.
-
-Each PR should be reviewed based on these criteria where applicable.
-
-### New production dependencies
-
-If a PR introduces new dependencies in `package.json`, paste the following
-checklist into the PR as a comment and check the items off before approving.
-
-**Tip** You should be able to copy and paste the section below directly into a
-GitHub comment, then check where criteria passed, strike out where not
-applicable.
-
-`## Review of dependencies`
-
-`- [ ]` Verify the dependency has previously been
-[pedigree reviewed](https://pedigree-service.wdc1a.cirrus.ibm.com)\
-`- [ ]` Verify the dependency [doesn't contain any vulnerabilities](https://snyk.io/vuln)\
-`- [ ]` Verify the dependency [bundle size](https://bundlephobia.com) is
-acceptable\
-`- [ ]` Verify the dependency is [actively maintained](https://www.npmtrends.com)\
-`- [ ]` Verify license conditions are met e.g. forwarding of copyright if
-necessary.
+# Release review checklists
 
 ## Component reviews for readiness
 
@@ -61,7 +33,7 @@ steps are needed:
 `- [ ]` One or more scenarios for a design pattern have been identified as a
 useful unit of functionality to publish.\
 `- [ ]` A functioning component or components delivering those scenarios have been
-delivered and merged to master.\
+delivered and merged to main.\
 `- [ ]` Design maintainer has approved the implementation for those scenarios
 (via a comment on the relevant issue/epic).
 
@@ -87,7 +59,10 @@ HTML attributes.\
 `- [ ]` No warnings, errors or log messages in the console.\
 `- [ ]` Each public component JS is exported in /src/components/index.js, each
 public component SCSS is included in /src/components/\_index.scss, and each
-public component has a flag in package-settings.js.
+public component has a flag in package-settings.js.\
+ `- [ ]` Each public component SCSS lists all of the Carbon and C&CS components
+imported and used by the JavaScript code and explicitly imports the SCSS for
+each of these components.
 
 `###` Standards
 
@@ -99,7 +74,7 @@ accessibility purposes -
 [read more here](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion).\
 `- [ ]` Code is formatted according to prettier rules (no use of //prettier-ignore).\
 `- [ ]` Code is clear, maintainable and follows standard React practices and the
-[code guidelines](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/.github/CONTRIBUTING.md).\
+[code guidelines](https://github.com/carbon-design-system/ibm-cloud-cognitive/blob/master/docs/CODE_GUIDELINES.md).\
 `- [ ]` Copyright header in every source file (js, css, scss etc.) with the appropriate
 years.