Skip to content

Latest commit

 

History

History
116 lines (86 loc) · 4.13 KB

guide.md

File metadata and controls

116 lines (86 loc) · 4.13 KB

Git Workflow Guide (Fork + Upstream Sync)

This guide is for contributors and maintainers working on this repository. To install assistant templates in your own project without cloning this repo, follow toolkit installation instead.

When working from a fork, origin points to your fork and upstream points to the source repo. Verify your remotes first. Use this workflow without losing the ability to sync cleanly from upstream.

git remote -v
# origin    https://github.com/<you>/aicodeguide.git (fetch/push)
# upstream  https://github.com/automata/aicodeguide.git (fetch/push)

Rule of thumb

Keep main as a clean mirror of upstream/main. Never commit directly on main — always work on a feature branch.

1. Make changes on a feature branch

Use Node.js 22 or newer and run the checks before committing:

git checkout main
git checkout -b feature/<short-name>
# ... edit files ...
npm ci
npm run check
git add <files>
git commit -m "<message>"
git push -u origin feature/<short-name>

Resolve failing checks before committing, and rerun them after further edits before opening or updating a PR. See Contributing and Validation for check coverage and manual client acceptance steps.

2. Contribute from the feature branch

Open a pull request from your feature branch on your fork, targeting automata/aicodeguide:main. Keep the branch until the upstream PR is merged. Do not merge fork-only commits into your mirror branch.

For changes that will remain specific to your fork, keep a separate integration branch (for example, fork-main). Merge feature branches there and merge upstream/main into that branch as needed; it is not a mirror and can diverge.

3. Sync main from upstream

Run this periodically to pull in changes from the original repo:

git checkout main
git fetch upstream
git merge --ff-only upstream/main
git push origin main

If --ff-only fails, stop: local main contains divergent history. Preserve those commits on a separate branch and reconcile deliberately. Do not reset or force-push a branch containing work you have not preserved.

Then rebase any in-progress feature branch on top of the refreshed main:

git checkout feature/<short-name>
git rebase main

Rebasing rewrites commits. Coordinate with collaborators before rebasing a shared branch; updating its remote may require an explicitly approved git push --force-with-lease.

4. Clean up after upstream merge and sync

After confirming that the PR is merged and its changes are present in the synced main:

git checkout main
git branch -d feature/<short-name>
git push origin --delete feature/<short-name>

After a squash or rebase merge, git branch -d may refuse because commit IDs differ. Verify the merged changes before deciding whether to force-delete the local branch; refusal is not a reason to discard unverified work.

5. Vendoring third-party content (toolkits/)

Third-party instructions, skills, and agents must originate from the actual upstream project, not be recreated from memory. Fetch a pinned commit:

curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/<commit-sha>/<path> -o <path>

Record exact provenance (commit URL, license, fetch date, checksums) in a SOURCES.md next to the vendored files - see toolkits/copilot/SOURCES.md for the pattern. Preserve upstream copyright and license notices when distributing or installing copies. Local safety and compatibility fixes are allowed only when documented as adaptations with their purpose and checks; do not label adapted files "verbatim". Keep unrelated upstream formatting unchanged.

Repo-owned scaffolds, installation tools, tests, and CI may be authored here.

6. Packaging and distribution

Follow Contributing and Validation for building a toolkit archive and the approvals required for distribution or publication. Generated .tgz archives are build artifacts, not source files to commit. Keep consumer setup instructions in the installation guide rather than duplicating version-specific commands here.