---
name: git-github
description: 'Git and GitHub operations for Drupal projects. Use when: creating commits, writing commit messages, creating or switching branches, pushing branches, opening pull requests, reviewing git status or diff, resolving merge conflicts, tagging releases, checking PR status, understanding the Square360 semi-gitflow branching strategy, CI/CD pipeline, any git or GitHub workflow task.'
---

# Git & GitHub — Square360 Conventions

## Commit Message Style

Square360 uses a variant of Conventional Commits. Format:

```
type(): short description in lowercase

Optional body — explain what and why, not how.
Wrap at 72 characters.

Optional footer:
Refs: CU-<task-id>
```

### Type Reference

Source: [Square360 Dev Standards — 3.8.1 Code commits and pull request titles](https://app.clickup.com/36022251/v/dc/12b9zb-34231/12b9zb-65271)

| Type | When to use |
|------|-------------|
| `fix():` | Fixing a bug or making a tweak to a feature you are working on |
| `feat():` | Introducing a new feature to the codebase |
| `chore():` | A task like config sync that is neither a fix nor a feature |
| `ci():` | A change to the CI workflow |
| `docs():` | Adding documentation to the codebase |
| `refactor():` | Reworking existing code to improve it |

### Scope — Always use the ClickUp Task CustomID

The parentheses are for scoping. Use the ClickUp task **CustomID** (all caps, as it appears in ClickUp) as the scope — this allows ClickUp's scanner to automatically link the commit to the ticket.

General format:
```
type(scope): description
```

Examples:
```
fix(YCBE-757): fix mobile and header interaction
```

Add `!` after the scope for extra emphasis on breaking or critical changes:
```
fix(YCBE-757)!: fix mobile and header interaction
```

If there is no ClickUp ticket, omit the scope and keep empty parens:
```
feat(): add QueueWorker for batch content imports
```

You can add additional context in the commit body:
```
feat(PROJ-123): add QueueWorker for batch content imports

Implements a QueueWorker plugin to process node imports in batches
of 50, preventing timeout issues on large content migrations.
```

### Epics or multiple tickets on a single branch

Use the ClickUp ticket you are actively working on as the scope, even if you are on an epic branch. This allows the Semantic Release GitHub Action to run on merge to master and generate releases and documentation automatically.

## Branch Naming

All branches are named for the **ClickUp ticket CustomID** they belong to, using the same lowercase-hyphen format:

```
<type>/<CU-TICKET-ID>-<short-description>
```

Examples:
```
feature/CU-PROJ-123-add-event-paragraph
fix/CU-PROJ-456-hero-image-alt-text
chore/CU-PROJ-789-config-sync-cleanup
```

The ClickUp CustomID in the branch name allows ClickUp to link commits and PRs to tickets automatically.

## Square360 Semi-Gitflow

Source: [Square360 Dev Standards — 3.8.2 Code Release Workflow](https://app.clickup.com/36022251/v/dc/12b9zb-34231/12b9zb-65291)

### Branch structure

```
master      ← protected — releases only, never pushed to directly
develop     ← protected — default branch, all ticket work merges here
<ticket>/*  ← individual ticket branches (named for ClickUp CustomID)
```

Both `master` and `develop` are **protected branches** — they require a pull request to receive code. Neither can be pushed to directly.

### Day-to-day feature workflow (WIP)

```
1. Cut a branch from develop:
   git checkout develop && git pull
   git checkout -b feature/CU-PROJ-123-my-feature

2. Commit following the conventional commits convention (see above).

3. Push and open a PR targeting develop:
   git push origin feature/CU-PROJ-123-my-feature
   gh pr create --base develop --title "feat(PROJ-123): add event listing paragraph"

4. Opening the PR triggers CI → creates a Pantheon multidev named for the
   PR number (e.g. pr-22). Subsequent pushes to the branch update that multidev.

5. After review and approval, merge the PR into develop.
   CI deploys the code to the weekly RC multidev (see below).
```

### QA, regression testing, and release workflow

```
1. When a PR merges to develop, CI deploys to a release candidate multidev
   named for the work week: rc-YYYY-WW  (e.g. rc-2026-13).
   Multiple merges in the same week all land on the same RC multidev.

2. The developer runs a regression check on the RC multidev.
   Team members can be asked to validate the deploy.

3. Visual Regression Testing (optional):
   Add [vrt] to the PR description before merging to trigger automated
   visual diff tests between the RC multidev and LIVE.

4. When the week's work is regression-tested and approved, open a release PR:
   - Source: develop   →   Target: master
   - Title format: "Release YYYY-MM-DD"  (e.g. "Release 2026-03-30")
   - Description: list all PRs merged since the last release

5. Merging the release PR into master triggers CI → deploys to the Pantheon
   DEV environment automatically.

6. The Pantheon deploy from DEV → TEST → LIVE is done manually by the
   developer via the Pantheon dashboard or Terminus.
   NEVER bypass this — code must not go to LIVE without manual sign-off.
```

### Hotfix workflow

For urgent production fixes that cannot wait for a weekly release:

```
1. Cut from master (not develop):
   git checkout master && git pull
   git checkout -b fix/CU-PROJ-999-critical-login-bug

2. Fix, commit, push, open PR targeting master.

3. After merge to master, back-merge to develop immediately to stay in sync:
   git checkout develop && git pull
   git merge master
   git push origin develop
```

## CI / GitHub Actions Pipeline

| Trigger | CI action |
|---------|-----------|
| PR opened/updated targeting `develop` | Creates/updates Pantheon multidev `pr-{number}` |
| PR merged into `develop` | Deploys to weekly RC multidev `rc-YYYY-WW` |
| PR merged into `master` | Deploys to Pantheon DEV environment |
| `[vrt]` in PR description | Runs visual regression tests vs LIVE before merge |

**Key rules:**
- CI uses `composer install` with the committed `composer.lock` — **never `composer update`**
- Never push code directly to Pantheon — all deployments go through CI
- The DEV → TEST → LIVE pipeline on Pantheon is always a **manual** developer action
- Workflow files live in `.github/workflows/` — see Atlas for Terminus/Pantheon operations

## Safety Rules

- NEVER `git push --force` without explicit developer confirmation
- NEVER `git reset --hard` without explicit developer confirmation
- NEVER commit directly to `master` or `develop` — always use a ticket branch
- NEVER push code directly to Pantheon — all deployments go through `master` → CI
- NEVER amend a commit that has already been pushed
- NEVER merge `develop` → `master` unless all CI checks on `develop` are green
- Always `git status` before and after staging to verify intent
- Check `.gitignore` covers `copilot.local.md` before first commit on a new project

## Common Commands Reference

```bash
# Start new work
git checkout develop && git pull
git checkout -b feature/CU-PROJ-123-my-feature

# Stage and commit
git status && git diff --staged
git add <specific-files>
git commit -m "feat(PROJ-123): description"

# Push and open PR
git push origin feature/CU-PROJ-123-my-feature
gh pr create --base develop --title "feat(PROJ-123): description"

# Check PR state
gh pr status
gh pr view

# Release
git checkout master && git pull
git merge develop
git push origin master
git tag v1.2.3 && git push origin v1.2.3
```

## Underlying Standard

Square360 uses a minimal subset of [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). Key rules from the spec that apply:

- Type is lowercase, followed by optional scope in parentheses, optional `!`, then `: description`
- `fix` and `feat` are semantically meaningful to SemVer tooling (`PATCH` and `MINOR` bumps respectively)
- `!` before the `:` signals a breaking change (maps to a `MAJOR` SemVer bump)
- A `BREAKING CHANGE:` footer (all caps) is the alternative to `!` — describes what broke
- Body begins one blank line after the description
- Footers begin one blank line after the body; use `Token: value` format

Square360 diverges from the full spec only by using the ClickUp CustomID as the mandatory scope, and by limiting the allowed types to the six listed above rather than the full Angular set.
