From b406cd16fafdaac33bb3a40371e2813fb5e0a12b Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:02:01 -0600 Subject: [PATCH 01/19] docs: project repository & version control (fixes #10) --- project-repository-version-control/readme.md | 163 +++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 project-repository-version-control/readme.md diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md new file mode 100644 index 00000000..d0c0b51a --- /dev/null +++ b/project-repository-version-control/readme.md @@ -0,0 +1,163 @@ +# Project Repository & Version Control + +A **project repository** is the atomic unit of collaboration, publication, and +reproducibility on SCIBASE. It behaves like a hybrid of a GitHub repository, a +Jupyter workspace, and a scientific preprint: one structured container that +holds everything a research effort produces — manuscripts, data, code, models, +protocols, results, and metadata. + +Each repository is an independent, git-backed unit. Repositories can be private +(draft), shared with collaborators, or published (citable, with a DOI). + +--- + +## 1. Repository Structure & Components + +A repository always exposes the following canonical layout: + +``` +/ +├── manuscript/ # Structured text: Markdown, LaTeX, or WYSIWYG +├── data/ # Uploaded datasets, structured tables, or linked APIs +├── code/ # Analysis scripts, notebooks, packages +├── notebooks/ # Jupyter-style interactive documents +├── results/ # Plots, figures, models, or trained weights +├── protocols/ # Editable experiment plans and lab procedures +└── metadata.json # DOI, authors, affiliations, funding, tags, schema.org +``` + +Top-level directories are optional; a repository must contain at least a +`metadata.json` to be created. Any directory may be added later. Ad-hoc files +at the repository root (e.g. a top-level `README.md` or `run_analysis.py`) are +allowed and versioned like everything else. + +### `metadata.json` + +The single source of truth for repository-level metadata: + +```json +{ + "name": "single-cell-atlas-of-mouse-liver", + "title": "A single-cell atlas of the mouse liver", + "doi": "10.5555/scibase.0000001", + "version": "1.0.0", + "tags": ["single-cell", "rna-seq", "liver"], + "authors": [ + {"name": "Daniel Wusu", "orcid": "0000-0000-0000-0000", "affiliation": "UAlberta EE"} + ], + "affiliations": ["University of Alberta"], + "funding": [{"funder": "NSERC", "grant": "RGPIN-2024-0000"}], + "schema.org": { + "@context": "https://schema.org", + "@type": "Dataset", + "license": "CC-BY-4.0" + } +} +``` + +The `metadata.json` also encodes schema.org markup so published repositories +are indexable by search engines and scholarly aggregators. + +--- + +## 2. File & Metadata Versioning + +- **Full version control** for every artifact — documents, datasets, and code — + with commit history, rollback, and tag support. +- **Git-native backend.** Each repository is a real git repository. Large files + (datasets, trained weights) are stored via Git LFS so history stays lean. +- **Semantic versioning.** Versions follow `MAJOR.MINOR.PATCH` (e.g. `v1.0`, + `preprint-v2.1`). Pre-release tags such as `preprint-v1.0-rc1` are supported. +- **Hash-based integrity.** Every blob is content-addressed (SHA-256). The tree + hash of a tagged commit is recorded alongside the tag, giving a + cryptographically verifiable fingerprint for reproducibility and citation. + +### Commit workflow + +``` +$ scibase commit -m "add normalized expression matrix" +$ scibase tag -v v1.0.0 +$ scibase rollback v0.9.0 +``` + +--- + +## 3. Collaboration & Forking + +- **Forking.** Any user can fork a published repository. Forks record their + parent repository in `metadata.json` (`derived_from`), preserving attribution + for downstream derivations. +- **Merge Requests (MRs).** Collaborators propose changes as MRs with discussion + threads, inline review comments, approvals, and a merge action. +- **Branching.** Parallel experiments or competing hypotheses live on branches; + branches can be compared and merged via MRs. +- **Provenance tracking.** Every commit records author, timestamp, and the + files changed, so "who contributed what, and when" is always recoverable. + +--- + +## 4. In-Browser Editors & Diffs + +- **Inline editors** for Markdown, LaTeX, CSV, JSON, and `.ipynb` notebooks. +- **Code-aware diffing** for Python, R, Julia, and other common languages. +- **Rich data diffs** for tables and structured datasets — row/column-level + change highlighting rather than raw text. +- **Visual revision timeline** for comparing versions and rolling back. + +--- + +## 5. Computation-Aware Reproducibility + +- **Auto-executed reproducibility pipelines.** Any repository can declare an + entrypoint (e.g. `run_analysis.ipynb` in `notebooks/` or `code/`). Executing + it from raw `data/` should regenerate `results/`. +- **Container support.** Repositories may ship a `Dockerfile` or `environment.yml` + (Conda) to pin the execution environment. +- **Raw data → code → outputs.** The platform verifies that outputs can be + reproduced from the committed raw data and committed code alone. +- **Execution sandboxes.** Pipelines run in isolated sandboxes for secure + runtime validation. + +--- + +## 6. Repository Identifiers & Citation + +- **DOIs.** A DOI is minted per repository and per tagged version via Crossref + or DataCite. +- **Auto-generated citations** in APA, MLA, and BibTeX formats from + `metadata.json`. +- **“Cite this project” badge** showing dynamic metadata and usage metrics + (views, downloads, citations). + +--- + +## 7. Programmatic Access & Export + +- **Public REST API** for project and data access: + - `GET /repos/{owner}/{name}` — repository metadata + - `GET /repos/{owner}/{name}/tree` — file listing + - `GET /repos/{owner}/{name}/blob/{path}` — file contents + - `POST /repos` — create a repository + - `PUT /repos/{owner}/{name}/blob/{path}` — write a file +- **Export bundles.** Any repository (or tagged version) can be exported as a + zipped package containing a manifest, full file tree, and `metadata.json`. +- **Git-compatible CLI** (`scibase` as shown above) for advanced contributors + and labs that prefer working from the terminal. + +--- + +## Optional Advanced Features (Post-MVP) + +- **Provenance tree visualization** — interactive graph of forks, merges, and + citations. +- **Immutable snapshots** published to IPFS (or an append-only ledger) for + long-term archival integrity. +- **Notebook diff viewer** with output/version playback. + +--- + +## Why This Matters + +Reproducibility, transparency, and collaboration are mission-critical. A robust +project repository system with integrated version control underpins the +platform's credibility, researcher trust, and long-term archival integrity. \ No newline at end of file From e6ec5f4ce78834eb10d3ac4b740abe3c11f999e1 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Wed, 26 Aug 2026 19:15:07 -0600 Subject: [PATCH 02/19] docs: document fork attribution field in metadata.json --- project-repository-version-control/readme.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index d0c0b51a..26b55d4b 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -58,6 +58,13 @@ The single source of truth for repository-level metadata: The `metadata.json` also encodes schema.org markup so published repositories are indexable by search engines and scholarly aggregators. +Forks additionally record their parent repository via `derived_from`, preserving +attribution for downstream derivations (see [§3](#3-collaboration--forking)): + +```json +"derived_from": "https://scibase.ai/repos/danwusu/mouse-liver-atlas" +``` + --- ## 2. File & Metadata Versioning From bf27d6bc5518a0da5e924900bafe5a9dddf0df06 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Wed, 26 Aug 2026 23:39:16 -0600 Subject: [PATCH 03/19] docs: specify export bundle manifest format --- project-repository-version-control/readme.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 26b55d4b..651be301 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -148,6 +148,23 @@ $ scibase rollback v0.9.0 - `PUT /repos/{owner}/{name}/blob/{path}` — write a file - **Export bundles.** Any repository (or tagged version) can be exported as a zipped package containing a manifest, full file tree, and `metadata.json`. + The manifest records the repository identity, tagged version, tree hash, and + every file with its SHA-256 so a bundle is self-verifying: + + ```json + { + "schema_version": "1", + "repository": "danwusu/mouse-liver-atlas", + "version": "1.0.0", + "tree_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "exported_at": "2026-08-26T00:00:00Z", + "files": [ + {"path": "metadata.json", "sha256": "…", "size": 1234}, + {"path": "data/matrix.csv", "sha256": "…", "size": 48291} + ] + } + ``` + - **Git-compatible CLI** (`scibase` as shown above) for advanced contributors and labs that prefer working from the terminal. From 07ab2f51076f7038ef25184decc48f13d3115af7 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Thu, 27 Aug 2026 00:45:27 -0600 Subject: [PATCH 04/19] docs: address issue #10 (fixes #10) --- project-repository-version-control/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 651be301..ee1fa39d 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -81,7 +81,7 @@ attribution for downstream derivations (see [§3](#3-collaboration--forking)): ### Commit workflow -``` +```console $ scibase commit -m "add normalized expression matrix" $ scibase tag -v v1.0.0 $ scibase rollback v0.9.0 From 5462911dc48ade940d25df51446fc41f4b118c6e Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Thu, 27 Aug 2026 01:02:56 -0600 Subject: [PATCH 05/19] docs: address issue #10 (fixes #10) --- project-repository-version-control/readme.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index ee1fa39d..8df32049 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -132,7 +132,23 @@ $ scibase rollback v0.9.0 - **DOIs.** A DOI is minted per repository and per tagged version via Crossref or DataCite. - **Auto-generated citations** in APA, MLA, and BibTeX formats from - `metadata.json`. + `metadata.json`. Given the example metadata in [§1](#1-repository-structure--components): + + ```text + APA: Wusu, D. (2026). A single-cell atlas of the mouse liver (Version 1.0.0) + [Data set]. SCIBASE. https://doi.org/10.5555/scibase.0000001 + MLA: Wusu, Daniel. "A Single-Cell Atlas of the Mouse Liver." SCIBASE, Version 1.0.0, + doi:10.5555/scibase.0000001. + BibTeX: @misc{wusu2026single, + author = {Wusu, Daniel}, + title = {A single-cell atlas of the mouse liver}, + year = {2026}, + publisher = {SCIBASE}, + version = {1.0.0}, + doi = {10.5555/scibase.0000001} + } + ``` + - **“Cite this project” badge** showing dynamic metadata and usage metrics (views, downloads, citations). From a53df7104d052397343f3d6ee0330188881f4cd3 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Thu, 27 Aug 2026 04:48:04 -0600 Subject: [PATCH 06/19] docs: clarify semantic versioning rules (fixes #10) --- project-repository-version-control/readme.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 8df32049..eea02809 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -73,8 +73,10 @@ attribution for downstream derivations (see [§3](#3-collaboration--forking)): with commit history, rollback, and tag support. - **Git-native backend.** Each repository is a real git repository. Large files (datasets, trained weights) are stored via Git LFS so history stays lean. -- **Semantic versioning.** Versions follow `MAJOR.MINOR.PATCH` (e.g. `v1.0`, - `preprint-v2.1`). Pre-release tags such as `preprint-v1.0-rc1` are supported. +- **Semantic versioning.** Released versions follow `MAJOR.MINOR.PATCH` + (e.g. `v1.0.0`, `v2.1.0`). Pre-release and preprint tags such as + `preprint-v2.1` or `preprint-v1.0-rc1` are supported; shortened `MAJOR.MINOR` + forms (e.g. `v1.0`) are accepted as aliases for the latest patch. - **Hash-based integrity.** Every blob is content-addressed (SHA-256). The tree hash of a tagged commit is recorded alongside the tag, giving a cryptographically verifiable fingerprint for reproducibility and citation. From 42af191e46b06b8ea7a258a4c5054444fa7da79e Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Thu, 27 Aug 2026 05:06:06 -0600 Subject: [PATCH 07/19] docs: specify cite-this-project badge endpoint (fixes #10) --- project-repository-version-control/readme.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index eea02809..4f35908a 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -152,7 +152,19 @@ $ scibase rollback v0.9.0 ``` - **“Cite this project” badge** showing dynamic metadata and usage metrics - (views, downloads, citations). + (views, downloads, citations). The badge is rendered from a canonical + endpoint and can be embedded anywhere: + + ```html + + Cite this project — DOI 10.5555/scibase.0000001, 482 views, 91 downloads, 12 citations + + ``` + + The badge resolves to the current version's citation (APA/MLA/BibTeX) and its + metrics stay live: every tag bumps the version string shown, and the counts + update from the same API that powers the repository's public page. --- From a2a2d97da7fff25f40af4efe7506a2f9319d7a30 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Thu, 27 Aug 2026 13:36:22 -0600 Subject: [PATCH 08/19] docs: make derived_from metadata snippet valid JSON (fixes #10) --- project-repository-version-control/readme.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 4f35908a..d99351f4 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -62,7 +62,9 @@ Forks additionally record their parent repository via `derived_from`, preserving attribution for downstream derivations (see [§3](#3-collaboration--forking)): ```json -"derived_from": "https://scibase.ai/repos/danwusu/mouse-liver-atlas" +{ + "derived_from": "https://scibase.ai/repos/danwusu/mouse-liver-atlas" +} ``` --- From b967c23f8e61414ba275804764bb45a9b33d77b5 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:06:14 -0600 Subject: [PATCH 09/19] docs: address issue #10 (fixes #10) --- project-repository-version-control/readme.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index d99351f4..84b15760 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -105,6 +105,19 @@ $ scibase rollback v0.9.0 - **Provenance tracking.** Every commit records author, timestamp, and the files changed, so "who contributed what, and when" is always recoverable. +### Collaboration workflow + +The same `scibase` CLI used for versioning ([§2](#2-file--metadata-versioning)) +drives the collaboration features: + +```console +$ scibase fork danwusu/mouse-liver-atlas # clone + record derived_from +$ scibase branch alt-normalization # parallel experiment branch +$ scibase commit -m "try CPM normalization on branch" +$ scibase mr create -b alt-normalization # propose a merge request +$ scibase mr merge alt-normalization # review & merge (with discussion) +``` + --- ## 4. In-Browser Editors & Diffs From c173dc246457f66686022b58626fd77fa798c385 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Thu, 27 Aug 2026 20:08:43 -0600 Subject: [PATCH 10/19] docs: list cite-this-project badge endpoint in REST API (fixes #10) --- project-repository-version-control/readme.md | 1 + 1 file changed, 1 insertion(+) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 84b15760..91ca40fc 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -189,6 +189,7 @@ $ scibase mr merge alt-normalization # review & merge (with discu - `GET /repos/{owner}/{name}` — repository metadata - `GET /repos/{owner}/{name}/tree` — file listing - `GET /repos/{owner}/{name}/blob/{path}` — file contents + - `GET /repos/{owner}/{name}/badge` — cite-this-project badge and metrics (see §6) - `POST /repos` — create a repository - `PUT /repos/{owner}/{name}/blob/{path}` — write a file - **Export bundles.** Any repository (or tagged version) can be exported as a From ea7a2334c6eb98d1adac814a84815088317a8180 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Thu, 27 Aug 2026 23:07:31 -0600 Subject: [PATCH 11/19] docs: clarify semantic versioning alias vs preprint tags (fixes #10) --- project-repository-version-control/readme.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 91ca40fc..f0cbb0f0 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -76,9 +76,9 @@ attribution for downstream derivations (see [§3](#3-collaboration--forking)): - **Git-native backend.** Each repository is a real git repository. Large files (datasets, trained weights) are stored via Git LFS so history stays lean. - **Semantic versioning.** Released versions follow `MAJOR.MINOR.PATCH` - (e.g. `v1.0.0`, `v2.1.0`). Pre-release and preprint tags such as - `preprint-v2.1` or `preprint-v1.0-rc1` are supported; shortened `MAJOR.MINOR` - forms (e.g. `v1.0`) are accepted as aliases for the latest patch. + (e.g. `v1.0.0`, `v2.1.0`). Shortened `MAJOR.MINOR` forms (e.g. `v1.0`) are + accepted as aliases for the latest patch. Pre-release and preprint tags such + as `preprint-v2.1` or `preprint-v1.0-rc1` are supported. - **Hash-based integrity.** Every blob is content-addressed (SHA-256). The tree hash of a tagged commit is recorded alongside the tag, giving a cryptographically verifiable fingerprint for reproducibility and citation. From 789ea8b1766af0fb9ad9e17c72a0638ae54e1bae Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Fri, 28 Aug 2026 02:44:53 -0600 Subject: [PATCH 12/19] docs: address issue #10 (fixes #10) --- project-repository-version-control/readme.md | 26 ++++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index f0cbb0f0..e68a8b27 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -197,19 +197,19 @@ $ scibase mr merge alt-normalization # review & merge (with discu The manifest records the repository identity, tagged version, tree hash, and every file with its SHA-256 so a bundle is self-verifying: - ```json - { - "schema_version": "1", - "repository": "danwusu/mouse-liver-atlas", - "version": "1.0.0", - "tree_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", - "exported_at": "2026-08-26T00:00:00Z", - "files": [ - {"path": "metadata.json", "sha256": "…", "size": 1234}, - {"path": "data/matrix.csv", "sha256": "…", "size": 48291} - ] - } - ``` +```json +{ + "schema_version": "1", + "repository": "danwusu/mouse-liver-atlas", + "version": "1.0.0", + "tree_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "exported_at": "2026-08-26T00:00:00Z", + "files": [ + {"path": "metadata.json", "sha256": "4bf2a5e11b6d3c2f8a9e0d1c5f7b3a6c8e2d4f6a9b0c1d3e5f7a8b9c0d1e2f3a4", "size": 1234}, + {"path": "data/matrix.csv", "sha256": "7a1d9e3f2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2", "size": 48291} + ] +} +``` - **Git-compatible CLI** (`scibase` as shown above) for advanced contributors and labs that prefer working from the terminal. From 3f792a7db87b7b9eb168ce6cb1627e9eb32e7cdc Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Fri, 28 Aug 2026 06:37:24 -0600 Subject: [PATCH 13/19] docs: keep export manifest JSON inside its list item (fixes #10) --- project-repository-version-control/readme.md | 26 ++++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index e68a8b27..1c82704c 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -197,19 +197,19 @@ $ scibase mr merge alt-normalization # review & merge (with discu The manifest records the repository identity, tagged version, tree hash, and every file with its SHA-256 so a bundle is self-verifying: -```json -{ - "schema_version": "1", - "repository": "danwusu/mouse-liver-atlas", - "version": "1.0.0", - "tree_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", - "exported_at": "2026-08-26T00:00:00Z", - "files": [ - {"path": "metadata.json", "sha256": "4bf2a5e11b6d3c2f8a9e0d1c5f7b3a6c8e2d4f6a9b0c1d3e5f7a8b9c0d1e2f3a4", "size": 1234}, - {"path": "data/matrix.csv", "sha256": "7a1d9e3f2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2", "size": 48291} - ] -} -``` + ```json + { + "schema_version": "1", + "repository": "danwusu/mouse-liver-atlas", + "version": "1.0.0", + "tree_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "exported_at": "2026-08-26T00:00:00Z", + "files": [ + {"path": "metadata.json", "sha256": "4bf2a5e11b6d3c2f8a9e0d1c5f7b3a6c8e2d4f6a9b0c1d3e5f7a8b9c0d1e2f3a4", "size": 1234}, + {"path": "data/matrix.csv", "sha256": "7a1d9e3f2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2", "size": 48291} + ] + } + ``` - **Git-compatible CLI** (`scibase` as shown above) for advanced contributors and labs that prefer working from the terminal. From 42cf301e30dda09c3ab0e02d728c5280992570b4 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Fri, 28 Aug 2026 07:10:38 -0600 Subject: [PATCH 14/19] docs: fix invalid SHA-256 hashes in export manifest example (fixes #10) --- project-repository-version-control/readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 1c82704c..301ef62e 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -205,8 +205,8 @@ $ scibase mr merge alt-normalization # review & merge (with discu "tree_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "exported_at": "2026-08-26T00:00:00Z", "files": [ - {"path": "metadata.json", "sha256": "4bf2a5e11b6d3c2f8a9e0d1c5f7b3a6c8e2d4f6a9b0c1d3e5f7a8b9c0d1e2f3a4", "size": 1234}, - {"path": "data/matrix.csv", "sha256": "7a1d9e3f2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2", "size": 48291} + {"path": "metadata.json", "sha256": "b586df06c59768ecc1374f73eb63f4a7965bc8b36eef111b9d2eda615f8c25e9", "size": 1234}, + {"path": "data/matrix.csv", "sha256": "02e5c81bfb0f22a0fef7e7313ff1259d1dc989d1ec907686364d5bb4e687029c", "size": 48291} ] } ``` From 7d781dd2ebd6a6aac1f059c78e5af5d3d1d76b5a Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Fri, 28 Aug 2026 09:06:37 -0600 Subject: [PATCH 15/19] docs: list export bundle endpoint in REST API (fixes #10) --- project-repository-version-control/readme.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 301ef62e..0cb89420 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -190,10 +190,12 @@ $ scibase mr merge alt-normalization # review & merge (with discu - `GET /repos/{owner}/{name}/tree` — file listing - `GET /repos/{owner}/{name}/blob/{path}` — file contents - `GET /repos/{owner}/{name}/badge` — cite-this-project badge and metrics (see §6) + - `GET /repos/{owner}/{name}/export` — download an export bundle (see below) - `POST /repos` — create a repository - `PUT /repos/{owner}/{name}/blob/{path}` — write a file - **Export bundles.** Any repository (or tagged version) can be exported as a - zipped package containing a manifest, full file tree, and `metadata.json`. + zipped package containing a manifest, full file tree, and `metadata.json`, + served from `GET /repos/{owner}/{name}/export`. The manifest records the repository identity, tagged version, tree hash, and every file with its SHA-256 so a bundle is self-verifying: From 38eded456fc245901747d47c6162d9f73cc6aa9b Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Fri, 28 Aug 2026 09:43:35 -0600 Subject: [PATCH 16/19] docs: address issue #10 (fixes #10) --- project-repository-version-control/readme.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 0cb89420..5a4cfc27 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -83,6 +83,18 @@ attribution for downstream derivations (see [§3](#3-collaboration--forking)): hash of a tagged commit is recorded alongside the tag, giving a cryptographically verifiable fingerprint for reproducibility and citation. +A tag records the semantic version, the commit tree hash, and a timestamp. The +same `tree_sha256` is what appears in the export bundle manifest ([§7](#7-programmatic-access--export)), so a downloaded bundle can be verified against the +tagged release it claims to be: + +```json +{ + "tag": "v1.0.0", + "tree_sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", + "committed_at": "2026-08-26T00:00:00Z" +} +``` + ### Commit workflow ```console From 6ea7a0e4854c43e28a6dcfd2f5faf280409cc188 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Fri, 28 Aug 2026 11:40:02 -0600 Subject: [PATCH 17/19] docs: list tagged-version endpoints in REST API (fixes #10) --- project-repository-version-control/readme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 5a4cfc27..eae662f2 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -200,7 +200,9 @@ $ scibase mr merge alt-normalization # review & merge (with discu - **Public REST API** for project and data access: - `GET /repos/{owner}/{name}` — repository metadata - `GET /repos/{owner}/{name}/tree` — file listing + - `GET /repos/{owner}/{name}/tree?ref={tag}` — file listing at a tagged version - `GET /repos/{owner}/{name}/blob/{path}` — file contents + - `GET /repos/{owner}/{name}/blob/{path}?ref={tag}` — file contents at a tagged version - `GET /repos/{owner}/{name}/badge` — cite-this-project badge and metrics (see §6) - `GET /repos/{owner}/{name}/export` — download an export bundle (see below) - `POST /repos` — create a repository From ab4a7fda868ec1bb0d7a46cd51c1e304a88df197 Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Fri, 28 Aug 2026 12:15:42 -0600 Subject: [PATCH 18/19] docs: align metadata.json name with canonical repo slug (fixes #10) --- project-repository-version-control/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index eae662f2..5db98bee 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -37,7 +37,7 @@ The single source of truth for repository-level metadata: ```json { - "name": "single-cell-atlas-of-mouse-liver", + "name": "mouse-liver-atlas", "title": "A single-cell atlas of the mouse liver", "doi": "10.5555/scibase.0000001", "version": "1.0.0", From 033e3dfae8d17d60cfdc0b43a0010f6c6ab4bd0d Mon Sep 17 00:00:00 2001 From: wanieldd <309034407+wanieldd@users.noreply.github.com> Date: Fri, 28 Aug 2026 12:32:52 -0600 Subject: [PATCH 19/19] docs: mention blockchain option for immutable snapshots (fixes #10) --- project-repository-version-control/readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/project-repository-version-control/readme.md b/project-repository-version-control/readme.md index 5db98bee..de8d32ca 100644 --- a/project-repository-version-control/readme.md +++ b/project-repository-version-control/readme.md @@ -236,8 +236,8 @@ $ scibase mr merge alt-normalization # review & merge (with discu - **Provenance tree visualization** — interactive graph of forks, merges, and citations. -- **Immutable snapshots** published to IPFS (or an append-only ledger) for - long-term archival integrity. +- **Immutable snapshots** published to IPFS or blockchain (an append-only + ledger) for long-term archival integrity. - **Notebook diff viewer** with output/version playback. ---