diff --git a/AUTHORING_GUIDELINES.md b/AUTHORING_GUIDELINES.md new file mode 100644 index 000000000..9e0f06f0c --- /dev/null +++ b/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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 83fd6ecec..2c17b3666 100644 --- a/CONTRIBUTING.md +++ b/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/` 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 diff --git a/package.json b/package.json index 1e7d3ad0a..18b75ebb3 100644 --- a/package.json +++ b/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", diff --git a/sites/package.json b/sites/package.json index 3c1f4b198..135166afd 100644 --- a/sites/package.json +++ b/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" diff --git a/sites/postcss-preset-env/README.md b/sites/postcss-preset-env/README.md index aa16a0e6f..e41ec4557 100644 --- a/sites/postcss-preset-env/README.md +++ b/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: