In this article

↑ Back to top

Starting a New Project

The Jetpack monorepo has dozens of projects in it. Hoping to implement a new project in the Jetpack monorepo? Read on to find out how.

Note that we recommend starting a discussion early to ensure there there isn’t already a similar project, it fits in the Jetpack monorepo ecosystem, and it has an acceptable name:

  • If you’re an Automattician, drop us a line in the #jetpack-crew Slack channel, along with a link to the associated P2 discussion.
  • If you’re not an Automattician, open an issue.

Starting from scratch

Once you’re ready to get started on the new project, create a branch, then run jetpack generate, which will load the project generation wizard, asking a few questions and creating the basic package within the /projects folder. Questions are as follows:

  • What type of project are you working on today?
    This will typically be js-packages (a JavaScript package), packages (a Composer package), or plugins (a WordPress plugin).
  • What is your project called?
    Here you specify the user-friendly name of the project.
  • Succinctly describe your project
    Tell everyone what your project does.
  • Do you plan to use WordPress core functions in your PHPUnit tests?
    Either true or false. If true, adds WorDBless support to your project. This is skipped for JavaScript packages.
  • Does this project need to be deployed publicly? (Create a mirror repo?)
    Either true or false. You can read more about mirror repos here.

JavaScript packages will get this additional question:

  • Which best describes this package?
    Only JS packages will get this question.

Plugins are presented with the following additional questions:

  • How do you want versioning to work for your plugin?
    Here you can decide to use WordPress-style vs. Semantic versioning. Either works; we don’t judge!
  • What is the plugin’s starting version?
    Provide the plugin’s starting version, or we’ll choose an initial alpha version for you.
  • Create a blank plugin or use the Starter plugin?
    If you choose the Starter plugin, we’ll copy in some boilerplate from /projects/plugins/starter-plugin.

Example output looks something like this:

$ jetpack generate
✔ What type of project are you working on today? · js-packages
✔ What is your project called? · myproject
✔ Succinctly describe your project: · Jetpack MyProject solves all the things
✔ Does this project need to be deployed publicly? (Create a mirror repo?) (Y/n) · false
✔ Which best describes this package? · js-src
Project created successfully! Happy coding!

Once that completes, you can add your code and push your pull request for review!

Importing an existing repo

While every repo is a bit different, to move development of an existing public repo into the Jetpack monorepo an Automattician might do something like we’ve outlined below.

Note that while a private repo could be imported similarly, you’d have a lot of auditing to do to make sure no old commits expose private information.

In the original repo

Before you move things over, make sure you do as much cleanup as possible to make the transition smooth. In particular, consider the following:

  • Set up PHP_CodeSniffer with our ruleset and fix any lints identified.
  • Merge any PRs that are ready to merge.

In the monorepo

We recommend preserving the history of the original repo, and below are some steps that have worked fairly well:

  • Use git remote add to add a new remote for the existing repo: git remote add existing-source-repo git@github.com:Automattic/existing-source-repo
  • git fetch existing-source-repo
  • Create a temporary branch based on the existing source repo: git checkout -b existing-repo/prepare-source existing-source-repo/trunk
  • Move the files to where they should live in the monorepo, e.g. git mv -k * .* projects/plugins/new-plugin
    • Note: You may need to do something like mkdir --parents ./projects/plugins/new-plugin if the destination folder does not yet exist.
    • Note: git filter-repo might be better but hasn’t been fully tested. See p9dueE-2on-p2#comment-5761
  • Commit the changes: git add --all && git commit -m "Prepare XXX for monorepo"
  • Create the branch for the actual import: git fetch origin && git checkout -b add/import-from-existing-repo origin/trunk
  • Run this: git merge --allow-unrelated-histories existing-repo/prepare-source. This will merge in the source plugin into the monorepo while maintaining all previous commits.
  • Create additional commits to clean up the new project: adjust tooling to use what the monorepo provides, remove unneeded tooling, set monorepo configuration in composer.json, etc.
  • Run linting and such. Commit anything necessary.
  • Run git push origin HEAD and create your PR. Add the “DO NOT MERGE” tag.
  • When it’s time to merge the PR:
    • Go to the GitHub settings page and enable the “Allow merge commits” setting.
    • Go to the PR. There should be a caret dropdown next to “Squash and Merge” which you can use to select “Create a merge commit” instead.
  • Clean up:
    • Go back to the settings and disable the “Allow merge commits” setting.
    • Delete the temporary branch: git branch -D existing-repo/prepare-source
    • If you want to move any open PRs from the old repo, check out the branches, git merge origin/trunk (and resolve any conflicts), push to origin, and recreate.
    • Remove the remote: git remote remove existing-source-repo
  • If you’re going to reuse the old repo as the mirror, reconfigure it to match the mirror repo guidelines.