fix some docs and add a very minimal general readme (#56)

* fix some docs and add a very minimal general readme * document python3 and coloaide usage * typo's
csstools · Dec 2, 2021 · ea518da · ea518da
1 parent 569046f
commit ea518da
Show file tree

Hide file tree

Showing 9 changed files with 71 additions and 12 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -12,6 +12,8 @@ Found a problem? Want a new feature?
 
 Remember, a bug is a _demonstrable problem_ caused by _our_ code.
 
+_If this guide itself is not working or is not clear, please report it._
+
 ## Submitting Pull Requests
 
 Pull requests are the greatest contributions, so be sure they are focused in
@@ -29,7 +31,12 @@ scope and avoid unrelated commits.
    git remote add upstream https://github.com/csstools/postcss-plugins.git
 
    # Install the tools necessary for testing
+   # Node 16 or higher is required to build and run tests.
+   # There is config for nvm and volta to help you use the right version.
    npm install
+
+   # Do an initial build of everything to make sure local dependencies can be found.
+   npm run build --workspaces
    ```
 
 2. Create a branch for your feature or fix:
@@ -42,10 +49,22 @@ scope and avoid unrelated commits.
    git checkout -b fix/something
    ```
 
-3. If your code follows our practices, then push your feature branch:
+3. Navigate to the plugin you want to contribute to.
+   ```bash
+   # Navigate to a plugin directory
+   cd plugins/<plugin-name>
+   ```
+   ```bash
+   # Navigate to the postcss-preset-env directory
+   cd plugin-packs/postcss-preset-env
+   ```
+
+4. If your code follows our practices, then push your feature branch:
    ```bash
+   # Run the linter
+   npm run lint
    # Test current code
-   npm test
+   npm run build && npm run test
    ```
    ```bash
    # Push the branch for your new feature

diff --git a/README.md b/README.md
@@ -1 +1,19 @@
-# TODO : make a README for this mono repo
+# PostCSS Plugins [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][postcss]
+
+[<img alt="build status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
+[<img alt="support chat" src="https://img.shields.io/badge/support-chat-blue.svg" height="20">][git-url]
+
+[PostCSS Plugins] contains tools and plugins for [PostCSS Preset Env].
+
+[PostCSS Preset Env] lets you convert modern CSS into something most browsers
+can understand, determining the polyfills you need based on your targeted
+browsers or runtime environments.
+
+[cli-img]: https://github.com/csstools/postcss-plugins/workflows/test/badge.svg
+[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
+[git-img]: https://img.shields.io/badge/support-chat-blue.svg
+[git-url]: https://gitter.im/postcss/postcss
+
+[PostCSS]: https://github.com/postcss/postcss
+[PostCSS Plugins]: https://github.com/csstools/postcss-plugins
+[PostCSS Preset Env]: https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env
diff --git a/packages/base-cli/README.md b/packages/base-cli/README.md
@@ -18,3 +18,5 @@ cli(
 	),
 );
 ```
+
+[postcss]: https://github.com/postcss/postcss
diff --git a/plugin-packs/postcss-preset-env/INSTALL.md b/plugin-packs/postcss-preset-env/INSTALL.md
@@ -186,7 +186,7 @@ module.exports = {
 [PostCSS]: https://github.com/postcss/postcss
 [PostCSS CLI]: https://github.com/postcss/postcss-cli
 [PostCSS Loader]: https://github.com/postcss/postcss-loader
-[PostCSS Preset Env]: https://github.com/csstools/postcss-preset-env
+[PostCSS Preset Env]: https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env
 [React App Rewire PostCSS]: https://github.com/csstools/react-app-rewire-postcss
 [React App Rewired]: https://github.com/timarney/react-app-rewired
 [Rollup Plugin PostCSS]: https://github.com/egoist/rollup-plugin-postcss
diff --git a/plugin-packs/postcss-preset-env/README.md b/plugin-packs/postcss-preset-env/README.md
@@ -1,7 +1,7 @@
 # PostCSS Preset Env [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS" width="90" height="90" align="right">][postcss]
 
 [<img alt="npm version" src="https://img.shields.io/npm/v/postcss-preset-env.svg" height="20">][npm-url]
-[<img alt="build status" src="https://github.com/csstools/postcss-preset-env/workflows/test/badge.svg" height="20">][cli-url]
+[<img alt="build status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
 [<img alt="support chat" src="https://img.shields.io/badge/support-chat-blue.svg" height="20">][git-url]
 
 [PostCSS Preset Env] lets you convert modern CSS into something most browsers
@@ -133,7 +133,7 @@ features.
 
 The `features` option enables or disables specific polyfills by ID. Passing
 `true` to a specific feature ID will enable its polyfill, while passing `false`
-will disable it. [List of IDs](https://github.com/csstools/postcss-preset-env/blob/master/src/lib/plugins-by-id.js#L36)
+will disable it. [List of IDs](https://github.com/csstools/postcss-plugins/blob/main/plugin-packs/postcss-preset-env/src/lib/plugins-by-id.js#L36)
 
 ```js
 postcssPresetEnv({
@@ -354,8 +354,8 @@ postcssPresetEnv({
 });
 ```
 
-[cli-img]: https://github.com/postcss/postcss-preset-env/workflows/test/badge.svg
-[cli-url]: https://github.com/postcss/postcss-preset-env/actions/workflows/test.yml?query=workflow/test
+[cli-img]: https://github.com/csstools/postcss-plugins/workflows/test/badge.svg
+[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
 [git-img]: https://img.shields.io/badge/support-chat-blue.svg
 [git-url]: https://gitter.im/postcss/postcss
 [npm-img]: https://img.shields.io/npm/v/postcss-preset-env.svg
@@ -366,7 +366,7 @@ postcssPresetEnv({
 [caniuse]: https://caniuse.com/
 [cssdb]: https://cssdb.org/
 [PostCSS]: https://github.com/postcss/postcss
-[PostCSS Preset Env]: https://github.com/csstools/postcss-preset-env
+[PostCSS Preset Env]: https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env
 [readme-style-with-preset-env-img]: https://csstools.github.io/postcss-preset-env/readme-style-with-preset-env.svg
 [readme-style-with-preset-env-url]: https://codepen.io/pen?template=OZRovK
 [readme-transform-with-preset-env-img]: https://csstools.github.io/postcss-preset-env/readme-transform-with-preset-env.svg

diff --git a/plugins/postcss-env-function/INSTALL.md b/plugins/postcss-env-function/INSTALL.md
@@ -157,6 +157,6 @@ grunt.initConfig({
 [PostCSS]: https://github.com/postcss/postcss
 [PostCSS CLI]: https://github.com/postcss/postcss-cli
 [PostCSS Loader]: https://github.com/postcss/postcss-loader
-[PostCSS Environment Variables]: https://github.com/csstools/postcss-env-function
+[PostCSS Environment Variables]: https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-env-function
 [React App Rewire PostCSS]: https://github.com/csstools/react-app-rewire-postcss
 [React App Rewired]: https://github.com/timarney/react-app-rewired
diff --git a/plugins/postcss-focus-visible/README.md b/plugins/postcss-focus-visible/README.md
@@ -2,7 +2,7 @@
 
 [<img alt="npm version" src="https://img.shields.io/npm/v/postcss-focus-visible.svg" height="20">][npm-url]
 [<img alt="CSS Standard Status" src="https://cssdb.org/badge/focus-within-pseudo-class.svg" height="20">][css-url]
-[<img alt="Build Status" src="https://github.com/csstools/postcss-focus-visible/workflows/test/badge.svg" height="20">][cli-url]
+[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
 [<img alt="support chat" src="https://img.shields.io/badge/support-chat-blue.svg" height="20">][git-url]
 
 [PostCSS Focus Visible] lets you use the `:focus-visible` pseudo-class in

diff --git a/plugins/postcss-lab-function/package.json b/plugins/postcss-lab-function/package.json
@@ -22,7 +22,6 @@
   "scripts": {
     "build": "rollup -c ../../rollup/default.js",
     "clean": "node -e \"fs.rmSync('./dist', { recursive: true, force: true });\"",
-    "generate-color-corpus": "python3 ./test/color/generate.py",
     "lint": "eslint src/**/*.ts src/**/*.js --no-error-on-unmatched-pattern",
     "prepublishOnly": "npm run clean && npm run build && npm run test",
     "stryker": "stryker run --logLevel error",

diff --git a/plugins/postcss-lab-function/test/color/README.md b/plugins/postcss-lab-function/test/color/README.md
@@ -0,0 +1,21 @@
+# Color unit tests.
+
+Reading :
+- https://github.com/w3c/csswg-drafts/issues/6816
+- https://github.com/csstools/postcss-lab-function/issues/7
+- https://github.com/w3c/csswg-drafts/issues/5191
+- https://facelessuser.github.io/coloraide/
+
+At the moment there is still unspecified behavior around color conversion from `lab`|`lch` to `rgb` or `color()`
+
+[coloraide](https://facelessuser.github.io/coloraide/) is used to mimic browser behavior.
+This allows us to quickly tweak the conversion and test the output against variants produced by coloraide.
+
+coloraide requires `python3`.
+
+```bash
+# USAGE:
+# python3 -m pip install coloraide
+# python3 ./test/color/generate.py
+```
+
-Original file line number
+Diff line change
@@ Expand Up / @@ -18,3 +18,5 @@ cli( @@
     	),
     );
     ```
+    [postcss]: https://github.com/postcss/postcss