From 1d219195c22bbce9b75ca2e31c10dbde4675c0ca Mon Sep 17 00:00:00 2001 From: Ville Laitila Date: Wed, 8 Apr 2026 20:39:59 +0300 Subject: [PATCH] Document fork-based contribution model and make CLAUDE.md agent-agnostic Adds a "Repository Model (Fork-Based Contribution)" section clarifying that softagram/sgraph is the canonical repo and contributors work via personal forks with origin (fork) + upstream (softagram/sgraph) remotes. Includes the crucial reminder to compare branches against upstream/main rather than just origin/main when reasoning about merge state, since forks can lag behind. Also rewords the header and one internal note so the guidance applies to any AI coding agent (Claude Code, Codex, Gemini CLI, ...) rather than naming Claude specifically. Only the filename follows the CLAUDE.md convention; the content is intentionally generic. --- CLAUDE.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5d4c1c4..adef195 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +This file provides guidance to AI coding agents (Claude Code, Codex, Gemini CLI, and similar) when working with code in this repository. The content is intentionally agent-agnostic; only the filename follows the `CLAUDE.md` convention. ## Project Overview @@ -8,6 +8,31 @@ sgraph is a Python library for working with hierarchic graph structures, typical The library is maintained by Softagram and is used for building information models about analyzed software. See also [sgraph-mcp-server](https://github.com/softagram/sgraph-mcp-server) for AI agent integration. +## Repository Model (Fork-Based Contribution) + +The canonical repository is `softagram/sgraph`. Contributors are expected to work from **personal forks** using the standard fork-and-PR model. + +A typical working clone has two remotes: + +| Remote | Purpose | Example URL | +|--------|---------|-------------| +| `origin` | Your personal fork (push target for feature branches) | `git@github.com:/sgraph.git` | +| `upstream` | The canonical Softagram repository (source of truth for `main`) | `git@github.com:softagram/sgraph.git` | + +**Important for coding agents:** when checking whether a branch's commits are already merged, always compare against `upstream/main`, not just `origin/main`. A contributor's fork may lag behind upstream, so commits that appear "unmerged" relative to `origin/main` can in fact already be live in the canonical repo. + +```bash +# Always fetch both before reasoning about merge state +git fetch origin main +git fetch upstream main + +# Are this branch's commits in the canonical main? +git rev-list --left-right --count upstream/main...HEAD +# → "N 0" means all HEAD commits are already in upstream/main (safe to switch/delete branch) +``` + +New contributors: fork `softagram/sgraph` on GitHub, clone your fork as `origin`, and add `softagram/sgraph` as `upstream`. Open PRs from feature branches on your fork against `softagram/sgraph:main`. + ## Development Commands ### Environment Setup