Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: update quick start guide #34656

Merged
merged 6 commits into from
Dec 18, 2023
Merged

Docs: update quick start guide #34656

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7529c02
Clarify quick start guide is geared for a12s
samiff Dec 14, 2023
54b495e
Cleanup cloning and install script steps
samiff Dec 14, 2023
f593f18
Move env checker script heading below install steps
samiff Dec 14, 2023
3d31a98
Adjust heading levels
samiff Dec 14, 2023
3d6e150
Move jtube a11n-only note to top of its section
samiff Dec 14, 2023
d9bdb2d
Add ngrok/jtube info to full dev-env guide
samiff Dec 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/development-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
- [Composer](#composer)
- [jetpack CLI](#jetpack-cli)
- [Check if your environment is ready for Jetpack development](#check-if-your-environment-is-ready-for-jetpack-development)
- [Testing Jetpack cloud features](#testing-jetpack-cloud-features)
- [Development workflow](#development-workflow)
- [Building your project](#building-your-project)
- [Syncing local changes with Unison](#syncing-local-changes-with-unison)
Expand Down Expand Up @@ -165,6 +166,14 @@ Once you're all set here, you can continue developing. If you're setting up an l

`jetpack build` will provide prompts to determine the project you need or you can pass it a complete command, like `jetpack build plugins/jetpack --with-deps`

### Testing Jetpack cloud features

In order to test features that require a WordPress.com connection and other network related Jetpack features, you'll need a test site that can create local HTTP tunnels.

If you're an Automattician, we recommend using [Jurassic Tube](./quick-start.md#setting-up-jurassic-tube).

For other methods, check out [ngrok](../tools/docker/README.md#using-ngrok-with-jetpack) or [another similar service](https://alternativeto.net/software/ngrok/).

# Development workflow

Once you have a local copy of Jetpack and all development tools installed, you can start developing.
Expand Down
74 changes: 38 additions & 36 deletions docs/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,23 @@

This guide is designed to get you up and running working with the Jetpack Monorepo quickly following recommended and supported guidelines.

This guide assumes you are using MacOS or a Linux machine and are an Automattician. For more detailed information, including alternate local dev environments, running unit tests, best coding practices, and more, you can use the [full Development Environment guide here](development-environment.md#clone-the-repository).
**This guide assumes you are using MacOS or a Linux machine and are an Automattician**. For more detailed information, including setting up local dev environments for all contributors, running unit tests, best coding practices, and more, you can use the [full Development Environment guide here](development-environment.md#clone-the-repository).

## Installation

### Using the installation script

To speed up the installation process, you may use our monorepo installation script. To do so:
- clone the Jetpack repo using one of these two methods:
- A public SSH key ([recommended](https://github.com/Automattic/jetpack/blob/trunk/docs/development-environment.md#clone-the-repository)): `git clone [email protected]:Automattic/jetpack.git`
- HTTPS: `git clone https://github.com/Automattic/jetpack.git`
- `cd` into the cloned `jetpack` folder.
- run `tools/install-monorepo.sh` from the monorepo root.
Once the installation is complete, continue onto the section [Running Jetpack locally](#running-jetpack-locally).

- Clone the Jetpack Monorepo:
- Using a public SSH key ([recommended](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)): `git clone [email protected]:Automattic/jetpack.git`
- Or use HTTPS: `git clone https://github.com/Automattic/jetpack.git`
- Note that the monorepo should not be cloned into the WordPress plugins directory. If you plan on not using the provided Docker environment, read the [full Development Environment guide here](development-environment.md#clone-the-repository) to find out how to add symlinks.
- `cd` into the cloned `jetpack` folder.
- Run `tools/install-monorepo.sh` from the monorepo root.
- You can use the [environment checker script](#check-if-your-environment-is-ready-for-jetpack-development) to confirm that all required tools are installed.

Once the installation is complete, continue onto the section [Running Jetpack locally](#running-jetpack-locally).

### Installing manually

Expand All @@ -26,11 +30,11 @@ Prior to installation, we recommend using [`Homebrew`](https://brew.sh/) to mana
- nvm: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash`

The Jetpack Monorepo requires various software to be installed on your machine.
- Start by cloning the GitHub repo using one of these two methods:
- A public SSH key ([recommended](https://github.com/Automattic/jetpack/blob/trunk/docs/development-environment.md#clone-the-repository)): `git clone [email protected]:Automattic/Jetpack.git`
- HTTPS: `git clone https://github.com/Automattic/jetpack.git`
- If you're not an Automattician, you can [fork the repo following the instructions here](https://docs.github.com/en/get-started/quickstart/contributing-to-projects).
- Note that the Monorepo should not be cloned into the WordPress plugins directory (you will see a warning on your plugins page in that case saying that the Jetpack Monorepo is not a plugin and shouldn't be installed as one). If you are not cloning into a Docker environment, read the [full Development Environment guide here](development-environment.md#clone-the-repository) to find out how to add symlinks.

- Clone the Jetpack Monorepo:
- Using a public SSH key ([recommended](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)): `git clone [email protected]:Automattic/jetpack.git`
- Or use HTTPS: `git clone https://github.com/Automattic/jetpack.git`
- Note that the monorepo should not be cloned into the WordPress plugins directory. If you plan on not using the provided Docker environment, read the [full Development Environment guide here](development-environment.md#clone-the-repository) to find out how to add symlinks.
- This software needs to be installed or updated system-wide:
- Bash (will need to be updated from default Mac version): `brew install bash`
- jq (JSON processor used in scripts): `brew install jq`
Expand All @@ -42,6 +46,20 @@ The Jetpack Monorepo requires various software to be installed on your machine.
- Jetpack CLI (an internal tool that assists with development): `pnpm install && pnpm jetpack cli link`
- [You can read more about using the CLI here](https://github.com/Automattic/jetpack/blob/trunk/tools/cli/README.md).

### Check if your environment is ready for Jetpack development

We provide a script to help you in assessing if everything's ready on your system to contribute to Jetpack.

```sh
tools/check-development-environment.sh
```

Running the script will tell you if you have your environment already set up and what you need to do in order to get it ready for Jetpack development:

- All green `YES` or `OK` messages mean you're ready to start
- Red `NO` messages mean something is wrong or missing, and a link will be provided to help you with a fix.
- Yellow messages indicate something optional is broken or missing.

## Running Jetpack locally

After everything is installed, you're ready to run Jetpack locally! While there are other supported methods of doing this, we recommend and support using Docker containers.
Expand All @@ -60,9 +78,11 @@ To setup Docker:

For more in depth Docker instructions, follow the [Docker environment for Jetpack Development guide](../tools/docker/README.md).

### Setting up Jurassic Tube
## Setting up Jurassic Tube

In order to test features that require a WordPress.com connection and other network related Jetpack features, you'll need a test site that can create local HTTP tunnels. If you're an Automattician, we recommend using Jurassic Tube:
In order to test features that require a WordPress.com connection and other network related Jetpack features, you'll need a test site that can create local HTTP tunnels. If you're an Automattician, we recommend using Jurassic Tube.

Note: This is for Automattician use only. For other methods, check out [ngrok](../tools/docker/README.md#using-ngrok-with-jetpack) or [another similar service](https://alternativeto.net/software/ngrok/).

**Warning: This creates a tunnel to your local machine which should not be trusted as secure. If it is compromised, so is your computer and everything it has access to. Only `jetpack docker jt-up` when needed for testing things that require the site to be publicly accessible, and `jetpack docker jt-down` when completed.**

Expand All @@ -77,27 +97,7 @@ In order to test features that require a WordPress.com connection and other netw
- Now, you can start your site with `jetpack docker jt-up`
- Your site should be available at `https://custom-subdomain.jurassic.tube`

Note: This is for Automattician use only. For other methods, check out [ngrok](https://github.com/Automattic/jetpack/blob/trunk/tools/docker/README.md#using-ngrok-with-jetpack) or [another similar service](https://alternativeto.net/software/ngrok/).

### Check if your environment is ready for Jetpack development

We provide a script to help you in assessing if everything's ready on your system to contribute to Jetpack.

```sh
tools/check-development-environment.sh
```

Running the script will tell you if you have your environment already set up and what you need to do in order to get it ready for Jetpack development:

- All green `YES` or `OK` messages mean you're ready to start
- Red `NO` messages mean something is wrong or missing, and a link will be provided to help you with a fix.
- Yellow messages indicate something optional is broken or missing.

#### Running Tests

To run PHP and JS tests, you can use the Jetpack CLI: `jetpack test` and then choose the project and type of test you'd like to run.

# Development Workflow
## Development Workflow

Once you have a local copy of Jetpack and all development tools installed, you can start developing.

Expand All @@ -110,6 +110,8 @@ By default the development build above will run once and if you change any of th
```sh
jetpack watch
```
### Running Tests

That's all!
To run PHP and JS tests, you can use the Jetpack CLI: `jetpack test` and then choose the project and type of test you'd like to run.

That's all!
Loading