Skip to content

Improve contributing documentation (DCO and signatures) - final - fine #14

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

Open
larinyo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Improve contributing documentation (DCO and signatures) - final - fine #14

Show file tree
Hide file tree
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
89 changes: 31 additions & 58 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,33 +6,12 @@
</tr>
</table>

⚠️ **Disclaimer:** Under active development. Code has not been audited. APIs and interfaces are subject to change!
⚠️ **Disclaimer:** Under active development. Code has not been audited, APIs and interfaces are subject to change!

Framespace Genesis [![Tests](https://github.com/Stream44/FramespaceGenesis/actions/workflows/test.yaml/badge.svg)](https://github.com/Stream44/FramespaceGenesis/actions/workflows/test.yaml?query=branch%3Amain)
===

*Experimental* implementations of [encapsulate](https://github.com/Stream44/encapsulate) based visual modeling engines. Models are constructed by defining components and events are generated by following an actual execution path through annotated code components.

Usage
--

[bun.sh](https://bun.sh) is required.

After cloning run:

```
bun install

# Generate data for viewing
bun test

# Start the workbench
bun dev

# Open browser
open http://localhost:3000
```

An *experimental* implementation of an [encapsulate](https://github.com/Stream44/encapsulate) based visual modeling engine. Models are constructed and events are generated by following an actual execution path through annotated code components.

Overview
===
Expand Down Expand Up @@ -67,61 +46,57 @@ The model **executes by following the actual codepath** — object method calls

These events are collected into a **boundary event log**. The schema and event log together drive a **schema-based, event-hydrated interactive visualization**.

**The primary rule:** construct a **promise graph** through all action invocations that touches every attribute and ends up in a resolved state when the model has finished executing.

![Implementation Approach](./engines/Concept.svg)

Model Engines
===

Engines implement queryable graph models to drive visualizations. Each engine supportes a specific set of model features.

LadybugDB engine for Encapsulate
---

Query [encapsulate](https://github.com/Stream44/encapsulate) *Capsule Source Tree* and *Membrane Event* related data from the [ladybugdb.com](https://ladybugdb.com/) embedded database engine.

See: [engines/Capsule-Ladybug-v0/](engines/Capsule-Ladybug-v0/)


Framespace Workbench
Visualizations
===

The workbench single-page-application presents all supported visual models for a selected **Capsule Spine Tree Instance** on the same page. The visualizations update in realtime as source code is modified.

See: [workbench/](workbench/)
### Quadrant Visual Model

![Framespace Workbench](./workbench/Screenshot.jpg)
The visualization is organized into **quadrants** with column and row trees that define the spatial layout. **Nested spaces** act as logical domains — the same identified space is the same space across quadrants, not just a visual container.

Inside spaces, **components** are the core unit. A component has **properties** (state) and **actions** (executable methods). Components can have multiple actions and attributes that define their visual and functional identity.

Visualizations
===
**Action invocations** connect components. An action payload moves from action to action — internal or external, one-to-one or fan-out to multiple invocations. Payloads crossing component and space boundaries emit **boundary crossing events** which makes execution observation possible.

### Framespace API
The primary rule: construct a **promise graph** through all action invocations that touches every attribute and ends up in a resolved state when the model has finished executing.

Inspect all APIs available to create visualizations to see what they return. This aids in model definition and visualization development.
![Quadrant Visual Model](./visualizations/Quadrant/Concept.svg)

See: [visualizations/FramespaceAPI/](visualizations/FramespaceAPI/)

Contributing
===

### Capsular Spine Visual Model
All contributions must comply with the repository’s Developer Certificate of Origin (DCO) and verified commit signature requirements.

Various visualizations to represent chains of [encapsulated](https://github.com/Stream44/encapsulate) components with animated execution activity.
Before opening a Pull Request:

See: [visualizations/CapsularSpine/](visualizations/CapsularSpine/)
1. Sign the DCO agreement once:
```bash
bun run sign-dco
```

2. Ensure every commit:

### Quadrant Visual Model
* Contains a `Signed-off-by:` trailer
* Is cryptographically signed (SSH or GPG)
* Has a clean working tree before using repository scripts

The visualization is organized into **quadrants** with column and row trees that define the spatial layout. **Nested spaces** act as logical domains — the same identified space is the same space across quadrants, not just a visual container.
3. Push your branch using the provided helper:

Inside spaces, **components** are the core unit. A component has **properties** (state) and **actions** (executable methods). Components can have multiple actions and attributes that define their visual and functional identity.
```bash
bun run push
```

**Action invocations** connect components. An action payload moves from action to action — internal or external, one-to-one or fan-out to multiple invocations. Payloads cross component and space boundaries making visual effects possible.
This will squash unsigned commits into a signed commit where possible.

See: [visualizations/Quadrant/](visualizations/Quadrant/)
⚠️ Important:

![Quadrant Visual Model](./visualizations/Quadrant/Concept.svg)
* The DCO check validates **all commits in the PR range**, not only the latest commit
* Verified signatures are enforced by repository rules
* Force-push may be restricted by branch protection; if you need to rewrite commits, create a new branch and open a new PR
* See the full contribution guide: [`docs/CONTRIBUTING.md`](./docs/CONTRIBUTING.md)


Provenance
Expand All @@ -143,6 +118,4 @@ Repository DID: `did:repo:e7b46f0978c2cc02461b480b99a6589a2b6fa888`

(c) 2026 [Christoph.diy](https://christoph.diy) • Code: [LGPL](./LICENSE.txt) & [MIT](./LICENSE.txt) • Text: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) • Created with [Stream44.Studio](https://Stream44.Studio)

### Contributing

All contributions must contain a [Developer Certificate of Origin](https://github.com/Stream44/dco). To contribute, sign `DCO.md` once using `bun run sign-dco` and push branches to github using `bun run push` which will squash unsigned commits into a signed commit.
262 changes: 262 additions & 0 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,262 @@
# Contributing to Framespace Genesis

Thank you for contributing to Framespace Genesis.

This repository enforces strong provenance and integrity guarantees. As a result, contributions must satisfy **three independent requirements**:

1. Developer Certificate of Origin (DCO)
2. Signed-off commit messages
3. Verified cryptographic commit signatures (SSH or GPG)

All three are required for CI to pass.

---

## Overview of Repository Rules

Before submitting a Pull Request, ensure that:

- You have signed the DCO agreement
- Every commit contains a `Signed-off-by:` trailer
- Every commit is cryptographically signed
- The working directory is clean when using repository scripts
- Branch protection rules may prevent force-pushes

Failing any of these will cause CI checks to fail.

---

## One-Time Setup (Required)

### 1. Install Bun

```bash
curl -fsSL https://bun.sh/install | bash
````

Verify:

```bash
bun --version
```

### 2. Configure Git Identity

Use the same email as your GitHub account:

```bash
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
```

---

## Configure Verified Commit Signing (SSH Recommended)

This repository enforces verified signatures.

### Step 1 — Enable SSH Signing in Git

```bash
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
```

If your key has a different name, list keys:

```bash
ls ~/.ssh/*.pub
```

### Step 2 — Configure Local Verification (Required by Git)

```bash
mkdir -p ~/.config/git
echo "$(whoami) $(cat ~/.ssh/id_ed25519.pub)" > ~/.config/git/allowed_signers
git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers
```

### Step 3 — Register Your Signing Key in GitHub

Go to:
GitHub → Settings → SSH and GPG Keys → New SSH Key

Important:

* Set **Key Type** to: `Signing Key`
* Do NOT add it only as an authentication key

---

## Sign the Developer Certificate of Origin (DCO)

Sign once per repository:

```bash
bun run sign-dco
```

This records your DCO agreement in the repository.

---

## Recommended Contribution Workflow (Golden Path)

This workflow avoids history rewriting and CI failures.

```bash
git checkout -b my-feature-branch
bun install

# Make your changes
git add .
git commit -S --signoff -m "Describe your change clearly"

git push -u origin my-feature-branch
```

Then open a Pull Request.

---

## Using the Repository Push Helper

The repository provides a helper:

```bash
bun run push
```

Behaviour:

* Requires a clean working directory
* May squash unsigned commits into a signed commit
* Does NOT automatically fix missing `Signed-off-by` trailers on older commits
* Will fail if untracked or unstaged files exist

---

## Common CI Failures and Fixes

### 1. Missing Signed-off-by Trailer

Error:

```
Missing: Signed-off-by trailer
```

Fix:

```bash
git commit --amend -S --signoff --no-edit
```

---

### 2. Missing Verified Signature

Cause:

* Git signing not configured
* Signing key not registered in GitHub as a Signing Key

Fix:

* Configure SSH signing (see above)
* Amend the commit:

```bash
git commit --amend -S --no-edit
```

---

### 3. DCO Fails for Older Commits in PR

The DCO check validates **all commits between `main` and your PR head**.

Inspect commit range:

```bash
git log --oneline origin/main..HEAD
```

If any commit is missing sign-off or signature, rewrite them:

```bash
git rebase -i HEAD~N
git commit --amend -S --signoff --no-edit
git rebase --continue
```

---

### 4. Force Push Blocked by Repository Rules

This repository may block force-push on branches.

If you rewrote commit history:

```bash
git checkout -b my-branch-fixed
git push -u origin my-branch-fixed
```

Then open a new Pull Request and close the old one.

---

### 5. Working Directory Not Clean (`bun run push` fails)

Example:

```
Working directory has uncommitted changes
```

Fix options:

* Commit the files
* Stash them:

```bash
git stash -u
bun run push
git stash pop
```
* Or ignore local artefacts (e.g. `bun.lock`) using:

```bash
echo "bun.lock" >> .git/info/exclude
```

---

## Pull Request Requirements

A Pull Request will only be mergeable when:

* All CI checks pass
* DCO validation passes
* Signature verification passes
* At least one reviewer with write access approves the PR

Contributors cannot merge their own PR without external approval due to repository governance rules.

---

## Final Verification Before Opening a PR

```bash
git log -3 --show-signature
git log -3 --pretty=%B
```

Ensure:

* Each commit shows a valid signature
* Each commit contains a `Signed-off-by:` line

````
Loading