From a6edfbbc4a508c1645b2aa02bc3ab63e0e2064dd Mon Sep 17 00:00:00 2001 From: quint-mbbdigital Date: Mon, 10 Aug 2026 15:01:57 -0400 Subject: [PATCH 1/3] docs: add CONTRIBUTING.md (fork, smoke, no-claim PRs) Root contributor guide: branch from main, infrastructure smoke, Level naming pointer, integrity links. Class A docs only. --- CONTRIBUTING.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 2 ++ 2 files changed, 80 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cf7dbc9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Contributing + +Thanks for interest in improving this repository. This project prioritizes +**reproducible experiment infrastructure** and honest reporting over positive +efficacy narratives. + +## Workflow + +1. Fork `CalculatedContent/nanogpt-experiments` (or push to your existing fork). +2. Branch from current **`main`** (not from stale feature branches). +3. Open a pull request against `CalculatedContent/nanogpt-experiments` `main`. +4. Prefer **small, single-theme** PRs (docs, logging, or one behavior change). + +## Before you open a PR + +From a clean checkout of your branch: + +```bash +# infrastructure smoke only — not a scientific result +./scripts/run_smoke_test.sh /tmp +``` + +Fix any smoke failures you introduced. Smoke success does **not** authorize +scaling-law, acceleration, or generalization claims. + +If your change touches the WW-PGD adapter or projection CSV schema, also run the +repository CI suite (or the subset your PR description names) and note results +in the PR body. + +## Naming: Level 0 is overloaded + +Schema/runner Levels 0–2 (`wwgpt --level N`) are **not** the same as the +`level_0_baseline/` / `level_0_wwpgd/` packages. See the root README section +**Level naming**. + +## PR expectations + +| Do | Don't | +|---|---| +| State whether the PR is docs-only, logging, or behavior | Claim WW-PGD efficacy or statistical significance from this stack alone | +| Keep defaults unchanged unless the PR is explicitly about a default | Fabricate α / invent missing spectral fits | +| Name any new log field and its definition | Treat smoke or notebook demos as publication results | +| Link related docs (`docs/SCIENTIFIC_INTEGRITY_POLICY.md`, `docs/CONTROL_ARMS.md`) when relevant | Bundle unrelated refactors with a one-line fix | + +Suggested PR body checklist: + +```text +## Type +- [ ] docs only +- [ ] logging / schema field +- [ ] behavior (describe default impact) + +## Summary +... + +## Test plan +- [ ] smoke / CI +- [ ] no scientific efficacy claim + +## Out of scope +... +``` + +## Where to look + +| Topic | Path | +|---|---| +| Root overview + level naming | [`README.md`](README.md) | +| Scientific integrity | [`docs/SCIENTIFIC_INTEGRITY_POLICY.md`](docs/SCIENTIFIC_INTEGRITY_POLICY.md) | +| Control arms | [`docs/CONTROL_ARMS.md`](docs/CONTROL_ARMS.md) | +| Troubleshooting | [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) | +| Baseline package (4L/128) | [`level_0_baseline/README.md`](level_0_baseline/README.md) | +| WW-PGD package sibling | [`level_0_wwpgd/README.md`](level_0_wwpgd/README.md) | + +## License + +By contributing, you agree that your contributions are licensed under the same +terms as this repository (`LICENSE`). diff --git a/README.md b/README.md index 4918e4c..32d45d1 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ This repository runs append-only, paired nanoGPT experiments comparing base optimizers with and without the repository's WW-PGD extension. It provides experiment infrastructure and descriptive analysis; it does **not** ship a scaling-law fit, acceleration conclusion, statistical-significance test, or alpha-generalization result. +See [CONTRIBUTING.md](CONTRIBUTING.md) for fork/PR workflow, smoke expectations, and no-claim norms. + ## Quick start on a local MacBook Run the repository from its checked-out `main` branch and keep the prepared corpus and results under `/tmp`: From 95c053a7d2b56f70d7abab7531aa5a62db81a6b4 Mon Sep 17 00:00:00 2001 From: quint-mbbdigital Date: Mon, 10 Aug 2026 15:02:13 -0400 Subject: [PATCH 2/3] docs: make Level naming note self-contained in CONTRIBUTING --- CONTRIBUTING.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf7dbc9..3df5310 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,9 +29,10 @@ in the PR body. ## Naming: Level 0 is overloaded -Schema/runner Levels 0–2 (`wwgpt --level N`) are **not** the same as the -`level_0_baseline/` / `level_0_wwpgd/` packages. See the root README section -**Level naming**. +Schema/runner Levels 0–2 (`wwgpt --level N`, `configs/levelN_*.yaml`) are **not** +the same as the `level_0_baseline/` / `level_0_wwpgd/` packages. Schema Level 0 is +typically **1 layer · 1 head · width 64**; the baseline packages use **4 layers · +4 heads · width 128**. Prefer the package READMEs when working under those folders. ## PR expectations From efc33831135a6e5dde300bb4086d4e4318ec95d7 Mon Sep 17 00:00:00 2001 From: quint-mbbdigital Date: Mon, 10 Aug 2026 15:33:43 -0400 Subject: [PATCH 3/3] docs: delineate external vs write-access contributor paths Fork is the no-push-access path only; collaborators branch on this repo. Integrity expectations apply to both; maintainers noted briefly. --- CONTRIBUTING.md | 40 +++++++++++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3df5310..06ce20f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,12 +4,39 @@ Thanks for interest in improving this repository. This project prioritizes **reproducible experiment infrastructure** and honest reporting over positive efficacy narratives. -## Workflow +This guide is for people sending **pull requests**. How you get a branch onto +GitHub depends on your access (see below). The **integrity / PR expectations** +apply to external and write-access contributors alike; maintainers may use a +shorter internal path for trivial fixes. -1. Fork `CalculatedContent/nanogpt-experiments` (or push to your existing fork). -2. Branch from current **`main`** (not from stale feature branches). -3. Open a pull request against `CalculatedContent/nanogpt-experiments` `main`. -4. Prefer **small, single-theme** PRs (docs, logging, or one behavior change). +## Who you are (access paths) + +| Role | Typical access | How you open a PR | +|---|---|---| +| **External contributor** | No push access to this repo | **Fork** the repo under your account, push a branch to *your* fork, open a PR into `CalculatedContent/nanogpt-experiments` `main` | +| **Collaborator / write access** | Can push branches to this repo | Create a branch on **this** repo from current `main`, push it here, open a PR into `main` (no personal fork required) | +| **Maintainer** | Admin / merge rights | Same as write access for reviewable changes; direct commits to `main` only for the project’s usual maintainer practice (prefer PRs for non-trivial work) | + +**Fork is not a social rank.** It is only the usual GitHub path when you cannot +push to this repository. If you already have write access, do not fork just to +satisfy a ritual. + +### External contributor (no write access) + +1. Fork `CalculatedContent/nanogpt-experiments`. +2. Branch from current upstream **`main`** (not from stale feature branches). +3. Push the branch to **your fork**. +4. Open a PR against `CalculatedContent/nanogpt-experiments` `main`. + +### Collaborator with write access + +1. Clone this repository (or add it as `origin`). +2. Branch from current **`main`**. +3. Push the branch to **this** repo. +4. Open a PR against `main`. + +Prefer **small, single-theme** PRs (docs, logging, or one behavior change) in +either path. ## Before you open a PR @@ -36,6 +63,9 @@ typically **1 layer · 1 head · width 64**; the baseline packages use **4 layer ## PR expectations +These expectations apply to **any** PR author (external or write-access), unless +a maintainer explicitly says otherwise for a given change. + | Do | Don't | |---|---| | State whether the PR is docs-only, logging, or behavior | Claim WW-PGD efficacy or statistical significance from this stack alone |