add authoring guidelines (#631)

* add authoring guidelines

* Update AUTHORING_GUIDELINES.md

Co-authored-by: Antonio Laguna <sombragriselros@gmail.com>

Co-authored-by: Antonio Laguna <sombragriselros@gmail.com>

Author: romainmenke

AUTHORING_GUIDELINES.md

@@ -0,0 +1,14 @@
+# Authoring guidelines
+
+We want to make it easier to write awesome CSS that works great in as many browsers as possible.
+Some of these browsers are a bit older, others don't yet exist.
+
+We will not place undue burden on anyone writing or maintaining CSS.
+
+We will only add a plugin to `postcss-preset-env` when the CSS WG invites implementations for the relevant features.
+
+We will not create plugins with features (or add features to plugins) that look and feel native but don't have a specification.
+
+We will make it clear that non-standard, pre-processor features are just that.
+
+We will only implement that which we know is correct and avoid side effects.

CONTRIBUTING.md

@@ -26,7 +26,7 @@ instructions:
 ### Quick start
 
 1. fork the repo and clone it locally
-2. `npm run get-me-going` to install and build dependencies
+2. `npm run setup-workspace` to install and build dependencies
 3. `cd plugins/<plugin-name>`
 4. `npm run build && npm run test` to build and test the plugin after making changes
 5. open a pull request with the changes
@@ -58,7 +58,7 @@ Receiving early feedback on your work will help you iterate more quickly in the
     # Install and build the needed things to start local development
     # This also does an initial test of everything.
     # If this gives errors please open an issue so that we can look into it.
-    npm run get-me-going
+    npm run setup-workspace
    ```
 
 * If you want to contribute to sites, you need to run the following command: 
@@ -67,7 +67,7 @@ Receiving early feedback on your work will help you iterate more quickly in the
     cd sites
     # Install the needed things to start local development
     # If this gives errors please open an issue so that we can look into it.
-    npm run get-me-going
+    npm run setup-workspace
    ```
 
 3. Create a branch for your feature or fix:
@@ -111,7 +111,7 @@ That’s it! Now [open a pull request] with a clear title and description.
 ## Creating a new plugin here
 
 - Follow the guide for submitting a pull request
-- Run `npm run get-me-going` if you want to start local development.
+- Run `npm run setup-workspace` if you want to start local development.
 - Run `npm run new-plugin` to create a new plugin.
 
 ```bash
@@ -147,7 +147,8 @@ Change "blue" to "purple" in "src/index.ts" and see how it affects the test outc
 
 - [PostCSS API documentation](https://postcss.org/api/)
 - [PostCSS guidelines for plugins](https://github.com/postcss/postcss/blob/main/docs/guidelines/plugin.md)
-- [CSSTools guidelines for plugins](https://github.com/csstools/postcss-plugins/wiki/Plugin-best-practices)
+- [CSSTools technical guidelines for plugins](https://github.com/csstools/postcss-plugins/wiki/Plugin-best-practices)
+- [CSSTools authoring guidelines](https://github.com/csstools/postcss-plugins/blob/main/AUTHORING_GUIDELINES.md)
 
 ## Trouble shooting
 

package.json

@@ -34,7 +34,7 @@
 	"scripts": {
 		"build": "npm run build --workspaces --if-present",
 		"clean": "bash ./.github/bin/clean.sh",
-		"get-me-going": "npm run clean && npm ci && npm run build && npm run test",
+		"setup-workspace": "npm run clean && npm ci && npm run build && npm run test",
 		"docs": "npm run docs --workspaces --if-present",
 		"lint": "npm run lint --workspaces --if-present && npm run lint:rollup-config && npm run lint:executable-files && npm run lint:licenses",
 		"lint:executable-files": "bash .github/bin/detect-executable-files/detect-executable-files.sh",

sites/package.json

@@ -17,7 +17,7 @@
 	},
 	"scripts": {
 		"clean": "git clean -dfx",
-		"get-me-going": "npm run clean && npm i",
+		"setup-workspace": "npm run clean && npm i",
 		"build": "npm run build --workspaces --if-present",
 		"lint": "npm run lint --workspaces --if-present",
 		"start": "npm run build --workspaces --if-present"

sites/postcss-preset-env/README.md

@@ -16,7 +16,7 @@ Before you can contribute to the codebase, you will need to fork the repo.
 
    # Install the needed things to start local development
    # If this gives errors please open an issue so that we can look into it.
-   npm run get-me-going
+   npm run setup-workspace
    ```
 
 This site is built using the following awesome packages: