# Shared Repo Setup Pattern

Use this file as the repeatable pattern for other Themovation products that should follow the same model as QuickCal.

This is the setup we proved end-to-end:

- local WordPress runtime with Docker / `wp-env`
- fast smoke test
- tag-based GitHub release flow
- hosted zip publishing
- update JSON publishing
- changelog JSON publishing
- Envato submission package build
- manual GitHub workflows for non-technical teammates
- optional GitHub workflow for Envato FTP upload

## What To Copy To Another Repo

For a new plugin or theme repo, the same shape should exist:

- `Makefile`
- `README.md`
- `STARTUP.md`
- `WORKSPACE.md`
- `RELEASE.md`
- `ENVATO.md`
- `CHANGELOG.md`
- `release-notes/`
- `test/wp-env/`
- `test/smoke/`
- `tools/release/`
- `.github/workflows/release.yml`
- `.github/workflows/build-release-downloads.yml`
- `.github/workflows/build-envato-package.yml`
- `.github/workflows/envato-upload.yml`

## Core Build Outputs

Every repo should decide its equivalent of these:

Hosted release downloads:

- stable zip
- versioned zip

Envato submission bundle:

- one `_envato_submission.zip` download from GitHub
- extracted contents ready for Envato FTP upload

Update feeds:

- primary update manifest JSON
- changelog JSON
- latest-version JSON if useful

## Recommended Workflow Split

Keep these responsibilities separate:

1. `release.yml`
   - used for real tagged releases
   - publishes hosted zips
   - publishes update manifests
   - creates GitHub Release

2. `Build Release Downloads`
   - manual workflow
   - outputs only the hosted download zips

3. `Build Envato Package`
   - manual workflow
   - outputs only `_envato_submission.zip`

4. `Upload To Envato`
   - manual workflow
   - builds `_envato_submission.zip`
   - extracts it
   - FTP uploads the extracted files

This split keeps the Actions UI understandable for non-technical teammates.

## Secret Groups

For repos following this pattern, secrets usually fall into 3 groups.

Hosted download server:

- `REPO_SSH_PRIVATE_KEY`
- `REPO_SSH_KNOWN_HOSTS`
- `REPO_RSYNC_DEST`

Update JSON server:

- `UPDATE_SSH_PRIVATE_KEY`
- `UPDATE_SSH_KNOWN_HOSTS`
- `UPDATE_RSYNC_DEST`

Envato FTP:

- `ENVATO_FTP_USERNAME`
- `ENVATO_FTP_PASSWORD`

If multiple repos share the same Envato account, prefer organization secrets with selected repo access.

## Repo-Specific Values You Need To Decide

For each new theme or plugin, define these early:

- slug
- release tag format
- main version file
- stable hosted zip name
- versioned hosted zip name
- update JSON URL
- changelog JSON URL
- Envato asset filenames
- local smoke pass/fail rules

## Theme vs Plugin Differences

The reusable pattern stays the same, but these parts usually differ:

Plugins:

- version source is usually the main plugin PHP file
- install zip usually contains only the plugin folder
- Envato customer package often contains plugin zip plus documentation

Themes:

- version source is usually `style.css`
- install zip may need a specific root folder name
- manual clean-install testing matters more because setup/import flows are heavier

## Minimum Adoption Checklist

When copying this pattern to another repo, make sure all of these are true before calling it done:

1. `make smoke` passes
2. release dry-run passes
3. real release works from a tag
4. hosted zip URLs update correctly
5. update JSON URL serves the current version
6. changelog JSON URL serves expected data
7. `_envato_submission.zip` contains the right customer files
8. GitHub manual workflows are understandable to a non-technical teammate
9. Envato FTP upload has been tested once

## Suggested Rollout Order For Other Themes

Do not migrate all themes at once.

Recommended order:

1. pick one shared theme with the simplest release flow
2. copy the QuickCal pattern
3. verify release, update JSON, and Envato upload once
4. use that as the theme template for the remaining products

## Practical Advice

- keep release and marketplace packaging logic in the repo, not in memory
- prefer manual GitHub workflows for teammate-friendly access
- automate only after the manual shape is correct
- avoid combining hosted download packaging and Envato packaging into one ambiguous artifact
- keep filenames human-readable and product-specific
