codespaces-grafting (aka cs-grafting)

A lightweight, shareable "live Codespace" / devcontainer scaffold. Graft this Codespace into an existing repository to give it an instant, reproducible development environment.

🌱 Quick metaphor (attention)
This project is to Codespaces what grafting is to gardening: you graft this Codespace template (the scion) into an existing repository (the stock) to add a ready-to-run development environment.

Who this is for

• Primary: WordPress plugin and theme authors (current templates and examples target WP).
• Secondary: Any project that wants a small, repeatable Codespace/devcontainer setup — the approach is intentionally generic.

Why use this

• ✨ Live Codespace: click the badge to create a Codespace from this template and export the scion into your repo (fastest path).
• ⚙️ Minimal & conservative: provides PHP, WP‑CLI and common tooling while preserving your project/editor settings.
• 🔁 Simple updater: graft.sh grafts the scion into your repo and helps you adopt template improvements safely.

Development tools included

• Web stack: Apache, MariaDB, PHP (with Xdebug)
• WordPress: WP-CLI for command-line WordPress management
• Code quality: Composer, PHP_CodeSniffer (phpcs) with WordPress Coding Standards
• DevOps: GitHub CLI (gh), REUSE tool for license compliance
• Common utilities: curl, jq, less, unzip

Terminology (short)

• scion — the Codespace/devcontainer template (.devcontainer/.vscode)
• stock — your repository getting the scion grafted
• graft — the act of applying the scion (graft.sh)

Quick start

• Easiest (live Codespace): click the Codespaces badge → create a Codespace → export the scion into your repository via the Codespace UI.
• From a workstation:

  curl -L -o ~/Downloads/graft.sh \
    https://raw.githubusercontent.com/evlist/codespaces-grafting/stable/.devcontainer/bin/graft.sh
  chmod +x ~/Downloads/graft.sh
  cd /path/to/your-repo
  bash ~/Downloads/graft.sh

  Inspect the changes, commit and push the files you want to keep.

Docs and maintainers

• Short maintainer docs ship with the scion at .devcontainer/docs/ so detailed guidance travels with the template and does not pollute stock repos.
• Current examples target WordPress; the pattern is reusable for other ecosystems.

Project structure (high level)

.
├── README.md
├── .devcontainer/                # scion (grafted into stock)
│   ├── README.md                 # scion maintainer notes
│   ├── docs/                     # extended scion docs (maintainers)
│   ├── assets/                   # icons, images used in scion docs
│   ├── devcontainer.json
│   ├── Dockerfile
│   ├── .cs_env                   # base environment variables
│   ├── .cs_env.d/                # additional env files (Debian .d style)
│   ├── bin/
│   │   └── graft.sh              # installer/updater (graft)
│   ├── sbin/
│   │   ├── bootstrap.sh          # container startup script
│   │   ├── bootstrap.sh.d/       # modular bootstrap hooks (Debian .d style)
│   │   └── merge-env.sh          # merges .cs_env and .cs_env.d/*
│   ├── tmp/                      # temporary files (gitignored)
│   ├── var/                      # runtime data (gitignored)
│   └── wp-content/               # WordPress content customizations
├── .vscode/                      # editor templates & stubs (managed)
└── plugins-src/                  # example/sample plugin(s) (WP-focused examples)

The scion uses Debian-style .d directories for modular configuration:

• .cs_env.d/: Environment variable overrides loaded in alphabetical order
• bootstrap.sh.d/: Startup hooks (10-aliases.sh, 20-plugins.sh, etc.) sourced sequentially

This makes customization easy: create .local.sh hooks (e.g., 25-themes.local.sh for themes, 40-import.local.sh for WP-CLI commands) that won't be overwritten during upgrades. See the FAQ for examples.

Want more?

• Maintainers: see .devcontainer/README.md for upgrade semantics and structure
• FAQ — frequently asked questions
• MAINTAINER.md — detailed procedures

📝 Note: This root README.md is not copied when grafting. Your stock repository keeps its own README. Only .devcontainer/ and managed .vscode/ files are grafted.

Support & Community

• Questions? Check the FAQ
• Report bugs or suggest features via GitHub Issues
• Contribute: See CONTRIBUTING.md for guidelines
• Discussions: Open a GitHub Discussion for ideas and feedback

License

This project is dual-licensed:

• GPL-3.0-or-later OR
• MIT

You may choose either license. See the LICENSE file and LICENSES/ directory for full texts.