Thank you for thinking about contributing to WordPress' Gutenberg project! If you're unsure of anything, know that you're 💯 welcome to submit an issue or pull request on any topic. The worst that can happen is that you'll be politely directed to the best location to ask your question, or to change something in your pull request. We appreciate any sort of contribution, and don't want a wall of rules to get in the way of that.
As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our Code of Conduct.
Before contributing, we encourage you to read our Contributing Policy (you're here already!) and our Handbook. If you have any questions on any of these, please open an issue so we can help clarify them.
All WordPress projects are licensed under the GPLv2+, and all contributions to Gutenberg will be released under the GPLv2+ license. You maintain copyright over any contribution you make, and by submitting a pull request, you are agreeing to release that contribution under the GPLv2+ license.
Gutenberg is a Node.js-based project, built primarily in JavaScript.
The easiest way to get started (on MacOS, Linux, or Windows 10 with the Linux Subsystem) is by running the Local Environment setup script, ./bin/setup-local-env.sh. This will check if you have everything installed and updated, and help you download any extra tools you need.
For other version of Windows, or if you prefer to set things up manually, be sure to have Node.js installed first. You should be running a Node version matching the current active LTS release or newer for this plugin to work correctly. You can check your Node.js version by typing node -v in the Terminal prompt.
If you have an incompatible version of Node in your development environment, you can use nvm to change node versions on the command line:
npx nvm install
npx nvm use
You should also have the latest release of npm installed, npm is a separate project from Node.js and is updated frequently. If you've just installed Node.js which includes a version of npm within the installation you most likely will need to also update your npm install. To update npm, type this into your terminal: npm install npm@latest -g
To test the plugin, or to contribute to it, you can clone this repository and build the plugin files using Node. How you do that depends on whether you're developing locally or uploading the plugin to a remote host.
First, you need a WordPress Environment to run the plugin on. The quickest way to get up and running is to use the provided docker setup. Install docker and docker-compose by following the most recent instructions on the docker site.
In the folder of your preference, clone this project and enter the working directory:
git clone [email protected]:WordPress/gutenberg.git
cd gutenberg Then, run a setup script to check if docker and node are configured properly and starts the local WordPress instance. You may need to run this script multiple times if prompted.
./bin/setup-local-env.sh
If everything was successful, you'll see the following ascii art:
Welcome to...
,⁻⁻⁻· . |
| ،⁓’. . |--- ,---. ,---. |---. ,---. ,---. ,---.
| | | | | |---' | | | | |---' | | |
`---' `---' `---’ `---’ ' ` `---' `---’ ` `---|
`---'
The WordPress installation should be available at http://localhost:8888 (username: admin, password: password).
Inside the "docker" directory, you can use any docker command to interact with your containers. If this port is in use, you can override it in your docker-compose.override.yml file. If you're running e2e tests, this change will be used correctly.
To bring down this local WordPress instance later run:
docker-compose down
If you'd like to see your changes reflected in this local WordPress instance, run:
npm install
npm run dev
Alternatively, you can use your own local WordPress environment and clone this repository right into your wp-content/plugins directory.
Next, open a terminal (or if on Windows, a command prompt) and navigate to the repository you cloned. Now type npm install to get the dependencies all set up. Then you can type npm run dev in your terminal or command prompt to keep the plugin building in the background as you work on it.
Open a terminal (or if on Windows, a command prompt) and navigate to the repository you cloned. Now type npm install to get the dependencies all set up. Once that finishes, you can type npm run build. You can now upload the entire repository to your wp-content/plugins directory on your webserver and activate the plugin from the WordPress admin.
You can also type npm run package-plugin which will run the two commands above and create a zip file automatically for you which you can use to install Gutenberg through the WordPress admin.
A good workflow for new contributors to follow is listed below:
- Fork Gutenberg repository
- Clone forked repository
- Create new branch
- Make code changes
- Commit code changes within newly created branch
- Push branch to forked repository
- Submit Pull Request to Gutenberg repository
Ideally name your branches with prefixes and descriptions, like this: [type]/[change]. A good prefix would be:
add/= add a new featuretry/= experimental feature, "tentatively add"update/= update an existing feature
For example, add/gallery-block means you're working on adding a new gallery block.
You can pick among all the tickets, or some of the ones labelled Good First Issue.
The workflow is documented in greater detail in the repository management document.
Gutenberg contains both PHP and JavaScript code, and encourages testing and code style linting for both. It also incorporates end-to-end testing using Google Puppeteer. You can find out more details in Testing Overview document.
This repository uses lerna to manage Gutenberg modules and publish them as packages to npm. Lerna automatically releases all the outdated packages. To check which packages are outdated and will be released, type npm run publish:check.
If you have the ability to publish packages, you must have 2FA enabled on your npmjs.com account.
Confirm that you're logged into npm, by running npm whoami. If you're not logged in, run npm adduser to login.
If you're publishing a new package, ensure that its package.json file contains the correct publishConfig settings:
"publishConfig": {
"access": "public"
}Run the following command to release a dev version of the outdated packages, replacing "123456" with your 2FA code. Make sure you're using a freshly generated 2FA code, rather than one that's about to timeout. This is a little cumbersome, but helps to prevent the release process from dying mid-deploy.
NPM_CONFIG_OTP=123456 npm run publish:devLerna will ask you which version number you want to choose for each package. For a dev release, you'll more likely want to choose the "prerelease" option. Repeat the same for all the outdated packages and confirm your version updates.
Lerna will then publish to npm, commit the package.json changes and create the git tags.
To release a production version for the outdated packages, run the following command, replacing "123456" with your (freshly generated, as above) 2FA code:
NPM_CONFIG_OTP=123456 npm run publish:prodChoose the correct version (minor, major or patch) and confirm your choices and let Lerna do its magic.
If you'd like to contribute to the design or front-end, feel free to contribute to tickets labelled Design. We could use your thoughtful replies, mockups, animatics, sketches, doodles. Proposed changes are best done as minimal and specific iterations on the work that precedes it so we can compare. If you use Sketch, you can grab the source file for the mockups (updated April 6th).
Documentation is automatically synced from master to the Gutenberg Documentation Website every 15 minutes.
To add a new documentation page, you'll have to create a Markdown file in the docs folder and add an item to the manifest file.
If you're contributing to the documentation of any component from the @wordpress/component package, take a look at its guidelines for contributing.
Please see SECURITY.md.
To translate Gutenberg in your locale or language, select your locale here and translate Development (which contains the plugin's string) and/or Development Readme (please translate what you see in the Details tab of the plugin page).
A Global Translation Editor (GTE) or Project Translation Editor (PTE) with suitable rights will process your translations in due time.
Language packs are automatically generated once 95% of the plugin's strings are translated and approved for a locale.
The eventual inclusion of Gutenberg into WordPress core means that more than 51% of WordPress installations running a translated WordPress installation will have Gutenberg's translated strings compiled into the core language pack as well.