Skip to content

docs: document fork-based contribution model and make CLAUDE.md agent-agnostic #153

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
villelaitila merged 1 commit into from
Apr 8, 2026
Merged

docs: document fork-based contribution model and make CLAUDE.md agent-agnostic #153

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,38 @@
# 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

sgraph is a Python library for working with hierarchic graph structures, typically used for representing software architectures. It provides data formats, structures, and algorithms for analyzing and manipulating software dependency graphs.

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:<you>/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
Expand Down
Loading