10up-toolkit/PROJECTS.md

Collection of reusable scripts for 10up development.

# 10up Projects (BETA)

**This subcommand is currently in BETA**

10up Toolkit provides a number of utlities for creating, managing, and deploying 10up specific projects.

## Anatomy of a Project

A standard 10up GitLab project initialized with 10up Toolkit looks like the following:

```
.tenup.yml
.gitlab-ci.yml
/scripts
  build.sh
```

`.tenup.yml` contains a number of variables the define the structure of the project e.g. the WordPress version and how to deploy the application.

`.gitlab-ci.yml` is a standard GitLab CI file that is generated by 10up Toolkit. It usually doesn't need to be edited but occassionally may need customization for more advanced CI workflows.

`build.sh` contains the commands for building a project. Engineers will need to edit this file to ensure it contains the proper build commands.

### .tenup.yml

`.tenup.yml` is automatically generated by the init command but you may want to create one yourself. Also, even after init, you will need to make sure it includes the proper values. Here is the anatomy of the file:

```yaml
project_name: "10up Project"
environments:
	production:
		branch: "trunk"
		wordpress_version: "6.4"
		deploy_to: "gitlab@1.1.1.1:/var/www/my-project"
		deploy_to_subdir: "wp-content/"
		deploy_from: "./"
		deploy_type: "rsync"
		url: "https://environmenturl.com"
	staging:
		branch: "staging"
		wordpress_version: "6.4"
		deploy_to: "gitlab@1.1.1.1:/var/www/my-project"
		deploy_to_subdir: "wp-content/"
		deploy_from: "./"
		deploy_type: "rsync"
		url: "https://environmenturl.com"
```

`deploy_from` and `deploy_to_subdir` let you choose what directory of your application deploys to which part of WordPress. `deploy_to` is the full remote path to WordPress. `deploy_from` is relative to the root of your project. `deploy_to_subdir` is relative to `deploy_to`. By default, it's set up such that the root of your application deploys to `wp-content`. Another setup is where your application is one level above WordPress e.g.

```
.tenup.yml
/wp
  /wp-content
```

In this scenario, `deploy_from` would be set to `wp` and `deploy_to_subdir` would be `./`.

`deploy_type` currently supports `rsync`, `wpe` (WP Engine), and `pantheon`. It defaults to `rsync`. If WPE or Pantheon is choosen, `deploy_to` should contain a Git URL. More deploy types will be added in the future.

## Commands

The project subcommand provides a variety of utlities for creating, building, and deploying 10up-specific projects.

List of commands:

```bash
10up-toolkit project init [--path=<path>] [--layout=<layout>] [--template=<Git repository>] [--name=<Project Name>] [--confirm] [--skip-composer] [--skip-ci]
```

`init` creates a project. You can optionally provide it a number of parameters or answer the prompts. If no path is provided, it will initialize the project in the current directory. If no layout is provided, it will default to `wpcontent` which means the project is rooted in `wp-content` (The other option is `wpparent` where the root of the project is one directory above WordPress). You will be prompted to choose a template e.g. [WP Scaffold](https://github.com/10up/wp-scaffold). Init will automatically search and replace prefixes using the project name you provide.

```bash
10up-toolkit project build [--type=<type>]
```

`build` will build your project e.g. `composer install`, `npm install`, and `npm run build`. It will execute all the `.sh` files in your `scripts/` directory where you can add custom build logic for your particular project. `--type` defaults to local e.g. build for your local environment. In CI, type will be set to `full`.

```bash
10up-toolkit project generate-ci [--confirm] [--path=<path>]
```

This command generates necessary CI files. For GitLab, this would be `.gitlab-ci.yml`. Right now this only supports GitLab but we will add support for GitHub in the future.

```bash
10up-toolkit project update-composer
```

Convenience function to update all dependencies in all found composer.json files. Also generates updated lock files.

**Note that generating CI files is currently in alpha and may require manual editing to fix issues.**