blueprints/CONTRIBUTING.md

Contribution Guidelines

We encourage you to contribute your own Blueprints to this repository!

Build your first Blueprint

Not sure how? Check out the Blueprints 101.

Submit your Blueprint to this repository

To keep the submission process smooth, please follow these guidelines:

Submit a Pull Request (PR) with your Blueprint. Consult this page Creating a pull request if you need a refresher on the process.

The PR should contain:

• A single blueprint.json file under the path blueprints/your-blueprint-name/blueprint.json (like the examples here).
• All the static files (WXR, ZIP, JPG, etc.) your Blueprint references. The static files must be loaded via the https://raw.githubusercontent.com URL pointing to your branch. raw.githubusercontent.com is a service that allows you to serve files directly from your GitHub repository. This is useful for loading static files in Blueprints. The URLs follow the raw.githubusercontent.com/${user}/${repo}/${branch}/${path} pattern.

For example, if you want to load a content-export.xml file, you create a new folder in the blueprints directory, /woocommerce-subscription (the name should correpond to the name of the blueprint). The folder must hold two files:

• A blueprints/woocommerce-subscriptions/blueprint.json file
• A blueprints/woocommerce-subscription/content-export.xml file

Assuming your branch is named /woo-subscription/, the Blueprint should reference as follows:

{
	"steps": [
		{
			"step": "importWxr",
			"file": {
				"resource": "url",
				"url": "https://raw.githubusercontent.com/wordpress/blueprints/woo-subscriptions/blueprints/woocommerce-subscriptions/content-export.xml"
			}
		}
	]
}

By submitting a Blueprint, you agree to license it under GPLv2 or later license.

Make sure to correctly indent your Blueprints using tabs using a code formatter like Prettier. This repository ships a .prettierrc file you could use. This is mostly to help the reviewers understand your Blueprint better. Every accepted and merged Blueprint will automatically be re-formatted using the .prettierrc file.

Blueprint metadata

Each Blueprint should include metadata within the top-level "meta" key of the blueprint.json file. Note that metadata is not required for all Blueprints, only for Blueprints submitted to this gallery.

Here's what's required:

• Title: a clear and concise name for your Blueprint.
• Author: your GitHub username, to let others know who created the Blueprint.

Optionally, you can add:

• Description: a brief explanation of what the Blueprint offers.
• Categories: specify relevant categories to help users find your Blueprint in the future Blueprints section on WordPress.org.

Here's an example:

{
	"meta": {
		"title": "WooCommerce Developer Environment",
		"description": "A local development environment for WooCommerce that includes WP-CLI.",
		"author": "zieladam",
		"categories": ["woocommerce", "developer environment"]
	}
}

Blueprint screenshots

To help your Blueprint stand out in the gallery, include a screenshot alongside blueprint.json:

• Add a JPEG named screenshot.jpg inside your Blueprint directory (for example, blueprints/my-blueprint/screenshot.jpg). JPEG keeps file sizes small and matches the automation that builds the site.
• Shoot in a landscape aspect ratio (≈16:9) at about 1600–2000px wide so the preview stays sharp on Retina displays, and try to keep it under ~500 KB.
• If you don't provide a screenshot, a CI job will generate one for you automatically.

Need help?

If you have questions or comments, open a new issue in this repository.