From 9f9f41af6ffff122b72811b8ad24fa49a62a2a5c Mon Sep 17 00:00:00 2001 From: Fabio Carvano Date: Sat, 17 Oct 2026 20:00:07 -0300 Subject: [PATCH] docs: document fork and upstream workflow --- CLAUDE.md | 11 +++-- CONTRIBUTING.md | 10 ++--- README.md | 6 +-- docs/dev/git-workflow.md | 90 +++++++++++++++++++--------------------- 4 files changed, 55 insertions(+), 62 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e441b184..63178193 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -186,12 +186,11 @@ modules// # specs grouped by product module (auth, sso, marketing ## Git Workflow -This repo mirrors to **two remotes** — `origin` pushes to both GitHub and Bitbucket, so a single `git push` lands on both. See **`docs/dev/git-workflow.md`** for the full procedure (remote layout, single-target pushes, keeping the remotes in sync). Key rules: - -- Default `git push` fans out to GitHub + Bitbucket. Use `git push github ` / `git push bitbucket ` for a single target. -- Work on a feature branch; open a PR into `main` (`gh pr create --base main`). Don't push to `main` directly; only the user merges. -- `.env.example` holds placeholders only — never commit real secrets. If GitHub push protection blocks a key, stop and tell the user; don't use the allow-secret bypass yourself. -- Fetch is GitHub-only: pull Bitbucket-direct changes with `git fetch bitbucket && git merge bitbucket/main`. +This repo uses a **fork workflow**: `origin` is your fork (the push target) and `upstream` is the official repository (read-only, push disabled). See **`docs/dev/git-workflow.md`** for the full procedure. Key rules: +- Create branches from `upstream/main`, push them to `origin`, and open a PR into `upstream` `main`. +- Never push to `upstream`. Its push URL is `no_push`. +- Keep your fork's `main` in sync with `upstream/main` using fast-forward only. +- Fetch both remotes: `git fetch upstream && git fetch origin`. ## Code Style diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 25030506..584c8626 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,12 +45,12 @@ Use the following prefixes for consistency: ### Rules -1. **Branch from `main`** and keep it up to date: +1. **Branch from the official `main`** (`upstream/main`) and keep your fork in sync: ```bash - git checkout main - git pull origin main - git checkout -b feat/your-feature + git fetch upstream + git checkout -b feat/your-feature upstream/main ``` + Push the branch to your fork (`git push -u origin feat/your-feature`) and open the PR from your fork into `offloadmemory/agentfork:main`. See [docs/dev/git-workflow.md](docs/dev/git-workflow.md). 2. **One concern per PR** — do not mix unrelated changes. 3. **Keep branches short-lived** — aim to merge within a few days. 4. **Delete branches after merge** — GitHub can do this automatically. @@ -101,4 +101,4 @@ We use [Conventional Commits](https://www.conventionalcommits.org/): ## Questions? -Open a [Discussion](https://github.com/kartikmanimuthu/agentfork/discussions) or reach out in an issue. \ No newline at end of file +Open a [Discussion](https://github.com/offloadmemory/agentfork/discussions) or reach out in an issue. \ No newline at end of file diff --git a/README.md b/README.md index 0bcbac4d..9a35982e 100644 --- a/README.md +++ b/README.md @@ -198,7 +198,7 @@ agentfork/ # Nx workspace root ### 1. Clone and install ```bash -git clone https://github.com/kartikmanimuthu/agentfork.git +git clone https://github.com/offloadmemory/agentfork.git cd agentfork bun install ``` @@ -392,8 +392,8 @@ E2e specs are grouped by module (`@auth`, `@sso`, `@marketing`, `@docs`, `@navig ## Contributing & Support - 🤝 **Contributing** — see [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and standards. -- 💬 **Questions & help** — see [SUPPORT.md](SUPPORT.md) or open a [Discussion](https://github.com/kartikmanimuthu/agentfork/discussions). -- 🐛 **Bugs & features** — open an [issue](https://github.com/kartikmanimuthu/agentfork/issues/new/choose). +- 💬 **Questions & help** — see [SUPPORT.md](SUPPORT.md) or open a [Discussion](https://github.com/offloadmemory/agentfork/discussions). +- 🐛 **Bugs & features** — open an [issue](https://github.com/offloadmemory/agentfork/issues/new/choose). - 🔒 **Security** — report privately per [SECURITY.md](SECURITY.md); never via public issues. - 📓 **Code of Conduct** — [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). diff --git a/docs/dev/git-workflow.md b/docs/dev/git-workflow.md index 348f13f1..9e031721 100644 --- a/docs/dev/git-workflow.md +++ b/docs/dev/git-workflow.md @@ -1,72 +1,66 @@ -# Git Workflow — Committing & Pushing (GitHub + Bitbucket) +# Git Workflow — Fork and Upstream -This repo lives in **two remotes** that must stay in sync. `origin` is configured to **push to both** at once, so a single `git push` lands on GitHub *and* Bitbucket. +This project uses a **fork-based workflow**: -> Audience: humans and AI agents. Follow the steps verbatim. Do not push, force-push, or rewrite history unless the user explicitly asks. +- `origin` is **your fork** of the repository. It is the default push target. +- `upstream` is the **official repository**. It is read-only for contributors: pushes to it are disabled. + +> Audience: humans and AI agents. Follow the steps in order. Do not push, force-push, or rewrite history unless the user explicitly asks. ## Remote layout -| Remote | Fetch | Push | Use for | +| Remote | Points to | Fetch | Push | | --- | --- | --- | --- | -| `origin` | GitHub | **GitHub + Bitbucket** | Default. A bare `git push` fans out to both. | -| `github` | GitHub | GitHub only | Push to GitHub alone. | -| `bitbucket` | Bitbucket | Bitbucket only | Push to / fetch from Bitbucket alone. | - -GitHub: `https://github.com/kartikmanimuthu/chatbot.git`Bitbucket: `git@bitbucket.org:acme/chatflow.git` +| `origin` | `https://github.com//agentfork.git` (your fork) | yes | yes | +| `upstream` | `https://github.com/offloadmemory/agentfork.git` (official) | yes | **disabled** (`no_push`) | -Verify with `git remote -v`. `origin` must list **two** push lines (GitHub then Bitbucket). If it doesn't, re-create the fan-out: +Set up the remotes once, after forking and cloning: ```bash -git remote set-url --add --push origin https://github.com/kartikmanimuthu/chatbot.git -git remote set-url --add --push origin git@bitbucket.org:acme/chatflow.git +git remote add upstream https://github.com/offloadmemory/agentfork.git +git remote set-url --push upstream no_push +git remote -v # upstream must show "no_push" on the push line ``` -## Standard commit + push +## Standard contribution flow -```bash -git status # confirm what you're committing -git add -A # or stage specific paths -git commit -m "type(scope): summary" # see commit message rules below -git push # → fans out to BOTH GitHub and Bitbucket -``` +1. Update your view of the official repository: + ```bash + git fetch upstream + ``` +2. Create a branch from the official `main` (not from your fork's `main`): + ```bash + git checkout -b docs/ upstream/main + ``` +3. Make your changes, then commit them (see commit message rules below). +4. Push the branch to your fork: + ```bash + git push -u origin docs/ + ``` +5. Open a pull request on GitHub: + - base repository: `offloadmemory/agentfork`, base branch: `main` + - head repository: your fork, compare branch: `docs/` -That's it. Commits are local until pushed; the single `git push` mirrors them to both repos. +## Keeping your fork's `main` up to date -### Single-target push (only when asked) +Your fork's `main` should match the official `main`, so that it always has the latest changes. ```bash -git push github # GitHub only -git push bitbucket # Bitbucket only +git fetch upstream +git checkout main +git merge --ff-only upstream/main +git push origin main ``` -## Before you push — checklist +If `--ff-only` fails, your `main` has commits the official repository does not have. Stop and ask the project owner before doing anything else. Do not force-push. + +## Before you push: checklist 1. **Verify the work.** Run `bun run typecheck` and `bun run test` (or `bun run verify`). Never claim success without seeing the commands pass. -2. **No secrets.** Never commit real credentials. `.env.example` holds *placeholders only*. GitHub push protection will block real keys (e.g. `AWS_BEARER_TOKEN_BEDROCK`, `AKIA…`). If blocked, **stop and tell the user** — do not use the allow-secret bypass URL on your own. -3. **Branch, don't push to** `main` **directly.** Work on a feature branch and open a PR into `main`(`gh pr create --base main`). Only the user merges. +2. **No secrets.** Never commit real credentials. `.env.example` holds placeholders only. If GitHub push protection blocks a commit, stop and tell the user. Do not use any bypass link on your own. +3. **Branch, don't push to `main` directly.** Work on a feature branch and open a PR into the official `main`. ## Commit message rules - Conventional Commits: `feat(...)`, `fix(...)`, `docs(...)`, `test(...)`, `build(...)`, etc. -- Imperative, one-line summary; body only if it adds context. -- AI agents append the configured `Co-Authored-By` trailer. - -## Keeping the two remotes in sync (important) - -The fan-out push only covers changes that flow **through this machine**. Two gotchas: - -1. **Fetch is GitHub-only.** If someone pushes *directly* to Bitbucket, you won't get it from `git pull`. Pull it in manually: - - ```bash - git fetch bitbucket - git merge bitbucket/main # ff-only when histories share a base - ``` - -2. **Both push legs must each fast-forward.** `git push` sends to GitHub first, then Bitbucket. If one side rejects (non-fast-forward), that half fails while the other may have already succeeded → the repos drift. On rejection: `git fetch` the rejecting remote, merge, push again. - -When in doubt about divergence, check: - -```bash -git fetch github && git fetch bitbucket -git rev-list --left-right --count github/main...bitbucket/main # 0 0 = in sync -``` \ No newline at end of file +- Imperative, one-line summary. Add a body only if it adds context.