From 835da0da58d86e9a4ef2f6a0d7739d4ff9ffe062 Mon Sep 17 00:00:00 2001 From: Sarah Norris Date: Fri, 13 May 2022 14:20:42 +0100 Subject: [PATCH] Add a contributing readme (#6002) * Add nvmrc file * Add new contributing.md file * Add SASS instructions & browser support * Add another link to contributing file * Reword sass final sentence * Add workflow and deployment sections --- .nvmrc | 1 + CONTRIBUTING.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 27 +----------- 3 files changed, 110 insertions(+), 26 deletions(-) create mode 100644 .nvmrc create mode 100644 CONTRIBUTING.md diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 000000000..19c7bdba7 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +16 \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..762e9460a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,108 @@ +# Guide to Contributing Code + +The following guide will help you through the process of contributing code to the themes repo. + +By contributing code to our free themes, you grant its use under the [GNU General Public License v2 (or later)](LICENSE). +## Prerequisites + +Our repo is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) which stores all the themes maintained by the Automattic Theme Team. We use [Node.js](https://nodejs.org/) to run utility functions from the top-level directory, and also to run commands for some themes, such as building the CSS files. We are currently using Node version 16. + +We recommend using the [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) since it is the easiest way to install and manage Node for macOS, Linux, and Windows 10. See the Node.js site for additional installation instructions. + +Also make sure you have an updated version of git installed on your computer, as well as a GitHub account. + +## Local Environment Setup + +We recommend setting up a local WordPress environment to test any changes. + +You can use the [wp-env package](https://github.com/WordPress/gutenberg/blob/trunk/packages/env/README.md) for setting up a WordPress environment locally. You'll need to install Docker to use wp-env. + +As an alternative to Docker setup, you can use [Local](https://localwp.com/), [WampServer](http://www.wampserver.com/en/), or [MAMP](https://www.mamp.info/), or even use a remote server. + +## Local Themes Setup + +Clone the repo locally and then install the dependencies: + +```bash +$ git clone git@github.com:Automattic/themes.git +$ cd themes +$ npm install +``` + +## Coding Standards + +Themes code should adhere to the [WordPress coding standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/). This repo contains a pre-commit hook which enables you to detect and fix code that doesn't follow the standards. + +To set this up follow these instructions: +1. Run `npm install` in the root of the repo. +2. Run `composer install` + +Now when you commit changes to a file PHPCBF will attempt to fix any issues with the file. + +This will also install the [WordPress-standard Prettier Configuration](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-prettier-config/) which can (optionally) be used in your IDE or command-line to format your code via [Prettier](https://prettier.io/docs/en/editors.html). + +### Browser Support + +We support the same browsers as WordPress Core, [listed here](https://make.wordpress.org/core/handbook/best-practices/browser-support/). + +## Contributing CSS + +A great way to get started with contributing to our themes is to pick up a CSS fix or patch. + +A lot of our themes use SASS for styling, and then use Node to compile the final CSS. Usually, these themes will have a `sass` directory ([example](https://github.com/Automattic/themes/tree/trunk/varia/sass)), and there will also be a `package.json` file at the root of the theme ([example](https://github.com/Automattic/themes/blob/trunk/varia/package.json)). + +In order to change the styles in these themes, you need to edit the SASS file first, and then run a build command to compile the CSS. Here is the process in most cases, using Varia as an example: + +1. Change to the theme's directory `cd varia` +2. Find the `.scss` file you need to edit in the `sass` directory +3. Make your changes +4. Run the build command using `npm run build` +5. You should see your updates in the newly built `.css` file/s + +If you are unsure what to do, leave us a comment so that we can improve documentation for other themes that may work differently. + +### Best Practices + +We use the latest features from the CSS, HTML and JS specifications, where our browser support will allow it. [Caniuse.com](https://caniuse.com/) is a great way to check if a feature is supported. + +We use intrinsic web design in our themes where possible. [Every Layout](https://every-layout.dev/rudiments/boxes/) is a good resource for this. + +## Workflow + +Here is a quick summary of our workflow: + +1. Create a pull request with your changes +2. Request a review of your PR +3. The Themes Team will provide feedback or approve your PR +4. The team will merge and deploy your PR (to both .com and .org) + +### Creating a pull request + +When your changes are ready for review you should create a pull request. Here are a couple tips for crafting a great pull request: + +* Include the purpose of your PR. Be explicit about the idea or issue your PR solves. +* Reference any existing issues that relate to your PR. This allows everyone to easily see all related discussions. + +The Themes Team will be notified when a new pull request is opened and we triage new issues and PRs regularly. Another good way to request a review is to add the team as Reviewers to your PR using the team handle, @Automattic/theam. + +Once your PR has been approved, the Themes Team will merge and deploy your change to both .com and .org. **Please note that merging a PR does not automatically deploy a change.** + +## Deployments + +The easiest way to deploy a change is to let the Themes Team handle it! This is because not everyone has a sandbox or the appropriate commit rights to handle a deployment. + +Deploying changes is part of the team's daily processes. We try to deploy approved changes as soon as possible, often multiple times a day. Please leave a comment if you have any questions or you want us to trigger a deploy. + +### Triggering a deployment + +If you have a sandbox and have the correct commit rights, you can use one of our sandbox tools to trigger your own deployment. + +From the top-level directory, run `npm run deploy` and follow the prompts. Please make sure to test your changes on your sandbox before completing the deployment. + +## Sandbox Tools + +If you use a sandbox to test or develop your themes you can use a couple of utilities to operate on that sandbox. + +- From the top-level directory, run `node ./theme-utils.mjs clean-sandbox` to bring the public themes GIT repository to a clean state. (This will only matter if your sandbox uses GIT such as how _WordPress.com_ is currently managed.) Alternately you can trigger that as an npm script: `npm run sandbox:clean`. `npm run sandbox:clean-all` will clean the entire sandbox. + +- From the top-level directory, run `node ./theme-utils.mjs push-to-sandbox` to push your entire working copy to the public themes folder of your sandbox. Alternately you can trigger this as an npm script: `npm run deploy:push:all` This command will rsync your local copy with the exception of anything in the `.sandbox-ignore` file. You should clean your sandbox before pushing any changes to it. `node ./theme-utils.mjs push-changes-to-sandbox` or `npm run deploy:push:changes` alternatively will push only files that have changed since the last deployment. diff --git a/README.md b/README.md index 04541dedd..2c76def2a 100644 --- a/README.md +++ b/README.md @@ -22,12 +22,7 @@ Here are some tips to consider for writing a useful report: ### Code -Patches and ideas in the form of code are always welcome! Here are a couple tips for crafting a great pull request: - -* Include the purpose of your PR. Be explicit about the idea or issue your PR solves. -* Reference any existing issues that relate to your PR. This allows everyone to easily see all related discussions. - -By contributing code to our free themes, you grant its use under the [GNU General Public License v2 (or later)](LICENSE). +Patches and ideas in the form of code are always welcome! A great way to get started is to work on a [CSS fix](https://github.com/Automattic/themes/blob/trunk/CONTRIBUTING.md#contributing-css) or a [Good First Issue](https://github.com/Automattic/themes/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). Please read our [full guide to contributing](https://github.com/Automattic/themes/blob/trunk/CONTRIBUTING.md) for more information. ### Testing pull requests @@ -47,18 +42,6 @@ By contributing code to our free themes, you grant its use under the [GNU Genera **Note:** In case the affected theme already exists on the WordPress site, it needs to be deleted before the theme zip file gets uploaded. -### Coding Standards - -Themes code should adhere to the [WordPress coding standards](https://make.wordpress.org/core/handbook/best-practices/coding-standards/). This repo contains a pre-commit hook which enables you to detect and fix code that doesn't follow the standards. - -To set this up follow these instructions: -1. Run `npm i` in the root of the repo. -2. Run `composer install` - -Now when you commit changes to a file PHPCBF will attempt to fix any issues with the file. - -This will also install the [WordPress-standard Prettier Configuration](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-prettier-config/) which can (optionally) be used in your IDE or command-line to format your code via (Prettier)[https://prettier.io/docs/en/editors.html]. - ### Packaging for WordPress.org Themes Showcase The code in this repository mirrors the code needed for the theme to function correctly on _WordPress.com_. To prepare a theme.zip that passes the _WordPress.org_ theme review automated test, do the following: @@ -67,11 +50,3 @@ The code in this repository mirrors the code needed for the theme to function co - View the generated zip in the respective theme's sub-directory Note that this script rebuilds the theme to strip it of .com-specific functionality, and discards any changes via git after doing so. _Make sure you have committed any working changes before running this script._ - -### Sandbox Tools - -If you use a sandbox to test or develop your themes you can use a couple of utilities to operate on that sandbox. - -- From the top-level directory, run `node ./theme-utils.mjs clean-sandbox` to bring the public themes GIT repository to a clean state. (This will only matter if your sandbox uses GIT such as how _WordPress.com_ is currently managed.) Alternately you can trigger that as an npm script: `npm run sandbox:clean`. `npm run sandbox:clean-all` will clean the entire sandbox. - -- From the top-level directory, run `node ./theme-utils.mjs push-to-sandbox` to push your entire working copy to the public themes folder of your sandbox. Alternately you can trigger this as an npm script: `npm run deploy:push:all` This command will rsync your local copy with the exception of anything in the `.sandbox-ignore` file. You should clean your sandbox before pushing any changes to it. `node ./theme-utils.mjs push-changes-to-sandbox` or `npm run deploy:push:changes` alternatively will push only files that have changed since the last deployment.