From 82cb69f5b9fd33d016ca944c345a9644ad25a8f7 Mon Sep 17 00:00:00 2001 From: Antonio Sejas Date: Wed, 7 Jun 2023 15:27:35 +0100 Subject: [PATCH] Docs: add WordCamp contributor day page (#528) Add a contributor day guide to https://wordpress.github.io/wordpress-playground/docs/start-here (See https://github.com/WordPress/playground-tools/issues/64). In particular, this commit: - Adds a new section on the Sidebar called `WordCamp Contributor Day` with URL `/wordpress-playground/docs/wordcamp-contributor-day` - Adds a new item under the quick start section on the main docs - Adds a new section on the main README Co-authored-by: Adam Zielinski --- README.md | 4 + .../docs/site/docs/01-start-here/01-index.md | 1 + .../site/docs/14-contributor-day/01-index.md | 108 ++++++++++++++++++ 3 files changed, 113 insertions(+) create mode 100644 packages/docs/site/docs/14-contributor-day/01-index.md diff --git a/README.md b/README.md index 085730cd5c..43fa043b93 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,10 @@ WordPress Playground is a building block that can power apps like: See [the WordPress.org announcement post](https://make.wordpress.org/core/2022/09/23/client-side-webassembly-wordpress-with-no-server/) to learn more about the vision. +## WordCamp Contributor Day + +If you're participating in a WordCamp Contributor Day, you can use the following instructions to get started: [WordCamp Contributor Day](https://wordpress.github.io/wordpress-playground/docs/wordcamp-contributor-day/). + ## Getting started WordPress Playground has a [live demo](https://developer.wordpress.org/playground/demo/) available. diff --git a/packages/docs/site/docs/01-start-here/01-index.md b/packages/docs/site/docs/01-start-here/01-index.md index eb786dac1a..054d3b7a78 100644 --- a/packages/docs/site/docs/01-start-here/01-index.md +++ b/packages/docs/site/docs/01-start-here/01-index.md @@ -20,6 +20,7 @@ This site (Documentation) is where you will find all the information you need to - [Build your first app](../03-build-an-app/01-index.md) with WordPress Playground - Use Playground as a zero-setup [local development environment](../04-nodejs/01-index.md#start-a-zero-setup-dev-environment-via-vscode-extension) - Read about the [limitations](../12-limitations/01-index.md) +- [WordCamp Contributor Day](../14-contributor-day/01-index.md) ## Take a deep dive diff --git a/packages/docs/site/docs/14-contributor-day/01-index.md b/packages/docs/site/docs/14-contributor-day/01-index.md new file mode 100644 index 0000000000..704fb9eb4f --- /dev/null +++ b/packages/docs/site/docs/14-contributor-day/01-index.md @@ -0,0 +1,108 @@ +--- +title: WordCamp Contributor Day +slug: /wordcamp-contributor-day +--- + +## Introduction + +The WordPress Playground VS Code extension and wp-now are tools that streamline the process of setting up a local WordPress environment. Both are powered by WordPress Playground, eliminating the need for other tools like Docker and MySQL. + +Read on to see how you can use either for contributing to WordPress. Please note that they’re currently in an alpha state and not all Make teams are fully supported. + +## Getting Started + +### VSCode Playground extension + +[Visual Studio Code Playground extension](https://marketplace.visualstudio.com/items?itemName=WordPressPlayground.wordpress-playground) offers a friendly user interface to a local WordPress environment. + +To get started, open your Visual Studio Code and navigate to the extensions tab. In the search bar, type 'WordPress playground' and click 'Install'. This will add a new icon on your sidebar. + +## wp-now + +### Minimum Requirements + +To get started with wp-now, you need to have Node and npm installed on your system. You can follow this guide to install them: [Node and npm installation guide](https://nodejs.org/en/download/package-manager). We also recommend using nvm to easily change the node version: [nvm installation guide](https://github.com/nvm-sh/nvm#installing-and-updating). + +### Installing + +You can globally install wp-now npm package in your machine, or if you prefer, you can run these commands directly from your browser using GitHub codespaces.: [https://www.npmjs.com/package/@wp-now/wp-now](https://www.npmjs.com/package/@wp-now/wp-now). + +``` +npm install -g @wp-now/wp-now +``` + +### Running + +To start a new server, navigate to your WordPress plugin or theme directory and run the command wp-now start. This will start the server with the default PHP and WordPress versions. A new tab will open automatically in your browser. + +``` +cd gutenberg +wp-now start +``` + +You can stop wp-now by killing the process by pressing the keys `CTRL + C`. + +To change the PHP or WordPress version, you can use the `--php` and `--wp` arguments. For example, to start a server with PHP 7.4 and WordPress 6.1, you can run: + +``` +wp-now start --php 7.4 --wp 6.1 +``` + +## Contributing to Gutenberg + +### Create a Gutenberg PR Step By Step + +Begin by creating a fork of the Gutenberg repository using your GitHub account. Once you've done that, clone your forked repository to your local machine to download the code. Following this, install the necessary dependencies and build the Gutenberg files. + +``` +git clone git@github.com:WordPress/gutenberg.git +cd gutenberg +npm install +npm run dev +``` + +Ensure that wp-now is installed on your system. Then, open a new terminal window and start the WordPress server by executing the wp-now command. + +``` +cd gutenberg +wp-now start +``` + +Commit and push your changes to your forked repository on GitHub and create a new pull request on the Gutenberg repository. + +For more in detail information, check the block editor handbook: https://developer.wordpress.org/block-editor/contributors/code/getting-started-with-code-contribution/#getting-the-gutenberg-code + +### Test a Gutenberg PR Step By Step + +To test a Gutenberg PR with wp-now, start by navigating to the PR on the Gutenberg repository. Once there, checkout the PR branch to switch your local environment to the version of the code that includes the proposed changes. After checking out the branch, pull the latest changes to ensure your local copy is up to date. Next, run npm install to ensure all dependencies are up to date. This step is crucial as it ensures that your testing environment matches the one in which the changes were made. Finally, test the changes in your local environment. This could involve running unit tests and manually testing features in a browser. + +``` +# copy the branch-name from GitHub +git checkout branch-name +git pull +npm install +npm run dev + +# In a different terminal inside the gutenberg folder +wp-now start +``` + +### Test a Gutenberg PR with the web version of WordPress Playground + +You can manually test a Gutenberg pull request directly from your browser. Given a pull request URL, https://github.com/WordPress/gutenberg/pull/51239, copy the ID (in this case, `51239`) and paste it at https://playground.wordpress.net/gutenberg.html. Use your specific pull request ID. Once you press "Go," your Pull Request will open in a new WordPress Playground where you can review the proposed changes! + +![Mermaid chart](https://github.com/WordPress/wordpress-playground/assets/779993/d4bc5a27-1401-4f35-bc68-2fad0ef699d5) + +## Contributing to other Make projects + +At this time, contributing to other Make projects is not fully supported at this time. + +## Known Limitations + +wp-now is in alpha version. Check out the known issues [https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md#known-issues](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md#known-issues). + +## Getting Help and Contributing to WordPress Playground + +If you encounter any issues when running your project with 'wp-now' or the VSCode Playground extension, don't hesitate to reach out to the Playground table or ask in the #meta-playground Slack channel. Someone will be around to assist you during the day. + +If you come across a bug or if you have an idea for a potential feature, we encourage you to share your input. You can create an issue on our GitHub repository at [https://github.com/WordPress/playground-tools](https://github.com/WordPress/playground-tools). Alternatively, you can share your thoughts in the ‘#meta-playground’ channel on Slack.