Zenodo publish

Zenodo Publish

Prepare research codebases for Zenodo deposition. Three modes: audit (score readiness), metadata (generate files), integrate (GitHub↔Zenodo setup).

Mode Detection

digraph mode_detection {
    "User request" [shape=box];
    "Contains audit/check/ready/score?" [shape=diamond];
    "Contains metadata/zenodo.json/citation/cff?" [shape=diamond];
    "Contains github/integrate/webhook/release?" [shape=diamond];
    "Ask which mode" [shape=box];
    "→ AUDIT mode" [shape=doublecircle];
    "→ METADATA mode" [shape=doublecircle];
    "→ INTEGRATE mode" [shape=doublecircle];

    "User request" -> "Contains audit/check/ready/score?";
    "Contains audit/check/ready/score?" -> "→ AUDIT mode" [label="yes"];
    "Contains audit/check/ready/score?" -> "Contains metadata/zenodo.json/citation/cff?" [label="no"];
    "Contains metadata/zenodo.json/citation/cff?" -> "→ METADATA mode" [label="yes"];
    "Contains metadata/zenodo.json/citation/cff?" -> "Contains github/integrate/webhook/release?" [label="no"];
    "Contains github/integrate/webhook/release?" -> "→ INTEGRATE mode" [label="yes"];
    "Contains github/integrate/webhook/release?" -> "Ask which mode" [label="no"];
}

Cross-mode nudge: If user runs metadata or integrate but has never run audit in this session, suggest (don't force): "Want me to run a quick Zenodo-readiness audit first?"

---

Mode 1: AUDIT

Score the repo's Zenodo-readiness. Report only — make NO changes.

What to Scan

Scan the repo root and up to 2 levels deep. Check these 4 dimensions:

1. Metadata (40% weight)

Check	Pass	Fail
.zenodo.json exists	✅ Found	❌ Missing
.zenodo.json valid schema	✅ All required fields present	⚠️ Missing required fields
CITATION.cff exists	✅ Found	⚠️ Missing (recommended)
CITATION.cff valid	✅ CFF v1.2.0 compliant	⚠️ Invalid format
LICENSE file present	✅ Found	❌ Missing — Zenodo requires a license
README.md exists	✅ Found with description	❌ Missing
Authors identifiable	✅ Names in metadata/git	⚠️ Only usernames, no real names

2. Repository Structure (25% weight)

Check	Pass	Fail
Clear entry point	✅ Main script/notebook obvious	⚠️ Unclear where to start
Scripts ordered/numbered	✅ Logical order (01_, 02_...) or workflow file	⚠️ Flat unordered scripts
Data separated from code	✅ data/ dir or external data refs	⚠️ Data mixed with scripts
No junk files	✅ Clean	❌ .DS_Store, __pycache__, Thumbs.db, .Rhistory, etc.
.gitignore present	✅ Found	⚠️ Missing
No IDE/editor configs committed	✅ Clean	⚠️ .vscode/, .idea/, .Rproj.user/

3. Reproducibility (20% weight)

Check	Pass	Fail
Environment lock file	✅ renv.lock / requirements.txt / environment.yml / conda.lock	❌ Missing
No hardcoded absolute paths	✅ Relative paths or here::here()	❌ /home/user/..., C:\Users\...
Random seeds documented	✅ set.seed() / random_state= present	⚠️ Stochastic code without seeds
Software versions recorded	✅ sessionInfo() / version pins	⚠️ No version info
Workflow documented	✅ Makefile / Snakefile / README instructions	⚠️ No execution order documented

4. Content Policy (15% weight)

Check	Pass	Fail
Total repo size	✅ Under 50GB	❌ Exceeds Zenodo limit
Large files flagged	✅ No files > 100MB	⚠️ Large files found (list them)
No secrets/credentials	✅ Clean	🔴 API keys, passwords, tokens detected
No sensitive data patterns	✅ Clean	🔴 Email lists, patient IDs, SSNs
Binary files justified	✅ None or documented	⚠️ Unexplained .exe, .dll, large binaries

Scoring

Each dimension: count passes / total checks → percentage.

Weighted total = (Metadata × 0.40) + (Structure × 0.25) + (Reproducibility × 0.20) + (Content × 0.15)

Score	Badge	Meaning
71-100	🟢 Ready	Can deposit with minor tweaks
41-70	🟡 Needs Work	Fixable issues, address before deposit
0-40	🔴 Not Ready	Significant gaps, needs cleanup first

Report Output

Produce a markdown artifact with:

# Zenodo Readiness Report
**Repository:** <repo name>
**Date:** <date>
**Score:** <score>/100 <badge>

## Dimension Scores
| Dimension | Score | Weight | Weighted |
|-----------|-------|--------|----------|
| Metadata | X% | 40% | X |
| Structure | X% | 25% | X |
| Reproducibility | X% | 20% | X |
| Content Policy | X% | 15% | X |

## Findings

### 🔴 Critical (must fix)
- ...

### 🟡 Recommended (should fix)
- ...

### 💡 Nice to Have
- ...

## Action Plan
Prioritized list with estimated effort per item.

---

Mode 2: METADATA

Generate .zenodo.json and CITATION.cff for the repository.

Step 1: Pre-fill Scan

Before presenting the form, scan for existing info:

Source	Fields extracted
DESCRIPTION (R packages)	Title, authors, license, description
pyproject.toml / setup.py / setup.cfg	Title, authors, license, version
package.json	Name, authors, license
git log --format='%aN <%aE>' | sort -u	Author names and emails
Existing CITATION.cff	All fields
Existing .zenodo.json	All fields
LICENSE file content	License type (SPDX detection)
README.md first paragraph	Description candidate

Step 2: Present Form

Present a single fill-in template. Pre-fill what was found, mark the rest blank:

Please fill in the metadata below. Pre-filled values are from your repo — edit as needed.
Leave blank if unknown. ★ = required.

★ Title: <pre-filled or blank>
★ Upload type: [dataset / software / publication / poster / presentation / lesson / image / video / other]
★ Description: <pre-filled or blank>

★ Authors (one per line — format: Last, First | ORCID | Affiliation):
  1. <pre-filled or blank>
  2.
  3.

★ License (SPDX identifier, e.g. MIT, GPL-3.0-only, CC-BY-4.0): <pre-filled or blank>

  Version: <pre-filled or blank>
  Language: <e.g. eng>
  Keywords (comma-separated):
  Publication date (YYYY-MM-DD):

  Grants (one per line — format: Funder: GrantID):
  1.
  2.

  Related identifiers (one per line — format: DOI relationship, e.g. 10.1234/foo isSupplementTo):
  1.
  2.

  Communities (Zenodo community slugs):
  1.

  Notes:

Wait for the user to fill in and reply.

Step 3: Generate Files

From the filled form, generate two files:

.zenodo.json

{
  "title": "...",
  "upload_type": "software",
  "description": "...",
  "creators": [
    {
      "name": "Last, First",
      "orcid": "0000-0000-0000-0000",
      "affiliation": "..."
    }
  ],
  "license": { "id": "MIT" },
  "keywords": ["..."],
  "related_identifiers": [
    {
      "identifier": "10.1234/foo",
      "relation": "isSupplementTo",
      "scheme": "doi"
    }
  ],
  "grants": [
    { "id": "10.13039/501100000780::123456" }
  ],
  "communities": [
    { "identifier": "zenodo" }
  ],
  "version": "1.0.0",
  "language": "eng",
  "publication_date": "2026-01-01",
  "notes": "..."
}

CITATION.cff

cff-version: 1.2.0
title: "..."
message: "If you use this software, please cite it as below."
type: software
authors:
  - family-names: "Last"
    given-names: "First"
    orcid: "https://orcid.org/0000-0000-0000-0000"
    affiliation: "..."
license: MIT
version: "1.0.0"
date-released: "2026-01-01"
keywords:
  - "..."

Overwrite protection: If either file already exists, show a diff between existing and generated content. Ask before overwriting.

Step 4: Validate Generated Files

Run these checks on the generated files:

Validation	Rule
Required fields	title, upload_type, description, creators present in .zenodo.json
ORCID format	Matches ^[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{3}[0-9X]$
License SPDX	Must be a valid SPDX identifier
Upload type enum	Must be one of: publication, poster, presentation, dataset, image, video, software, lesson, physicalobject, other
Date format	YYYY-MM-DD
Cross-file consistency	If both files generated, warn if title/authors/license/version differ between them
.zenodo.json wins	Remind user: when both files exist, Zenodo uses .zenodo.json and ignores CITATION.cff

Report all validation results. Fix any issues interactively.

---

Mode 3: INTEGRATE

Guide GitHub↔Zenodo integration. Validate existing metadata first.

Step 1: Validate Existing Metadata

• Check if .zenodo.json exists → validate against schema (same checks as Mode 2 Step 4)
• Check if CITATION.cff exists → validate format
• If neither exists → tell user to run metadata mode first, stop here
• If both exist → warn about precedence:

⚠️ Both .zenodo.json and CITATION.cff found. Zenodo will use .zenodo.json exclusively and ignore CITATION.cff. GitHub's citation widget will still use CITATION.cff. Make sure they're consistent.

Step 2: Integration Instructions

Present these steps:

## Setting Up GitHub↔Zenodo Integration

1. Go to https://zenodo.org/account/settings/github/
2. Log in with your Zenodo account (create one if needed)
3. Click "Connect" to link your GitHub account
4. Find your repository in the list and flip the toggle ON
5. Go to your GitHub repository
6. Create a new **Release** (not a pre-release):
   - Click "Releases" → "Create a new release"
   - Choose a tag (e.g., v1.0.0) — use semantic versioning
   - Title: match your .zenodo.json title + version
   - Click "Publish release" (NOT "Save draft", NOT "Pre-release")
7. Wait ~60 seconds, then check https://zenodo.org/account/settings/github/
   for the deposit status
8. Your DOI will appear on the Zenodo deposit page

Step 3: Pitfall Warnings

Always display these warnings after the instructions:

## ⚠️ Common Pitfalls

1. **Pre-releases are ignored** — Zenodo only processes full releases.
   Draft releases and pre-releases will NOT trigger a deposit.

2. **Metadata comes from the default branch** — Zenodo reads .zenodo.json
   from your DEFAULT branch (usually main/master) at the time of release,
   NOT from the tagged commit. Merge metadata changes before releasing.

3. **`.zenodo.json` overrides everything** — If .zenodo.json exists,
   CITATION.cff and GitHub repo metadata are completely ignored.

4. **~10GB snapshot limit** — GitHub integration snapshots your repo.
   Very large repos may fail. Consider using the Zenodo REST API directly
   for large deposits.

5. **Public repos only** — GitHub integration does not work with private
   repositories.

6. **Concept DOI vs Version DOI:**
   - Concept DOI: resolves to the LATEST version (changes over time)
   - Version DOI: permanent link to THIS specific version (never changes)
   - Use the Version DOI in your paper. Use the Concept DOI in your README.

7. **Failed deposits** — Check https://zenodo.org/account/settings/github/
   for error details. Common causes: invalid .zenodo.json, repo too large,
   or GitHub webhook misconfigured.

8. **Updating metadata after deposit** — You can edit metadata on Zenodo
   after deposit, but changes won't sync back to GitHub.

9. **Versioning** — Each new GitHub release creates a new version on Zenodo
   with its own Version DOI. The Concept DOI always points to the latest.

---

Zenodo-Specific Knowledge Reference

Upload Types

Type	When to use
software	Code, scripts, packages, tools
dataset	Data files, databases, processed results
publication	Papers, preprints, reports
poster	Conference posters
presentation	Slides, talks
lesson	Teaching materials, tutorials
image	Figures, photos, diagrams
video	Recordings, animations
other	Anything else

Common SPDX Licenses for Research

License	SPDX ID	Good for
MIT	MIT	Permissive, simple
GPL 3.0	GPL-3.0-only	Copyleft, derivative must be open
Apache 2.0	Apache-2.0	Permissive with patent grant
CC BY 4.0	CC-BY-4.0	Data/text, attribution required
CC BY-SA 4.0	CC-BY-SA-4.0	Data/text, share-alike
CC0 1.0	CC0-1.0	Public domain dedication
BSD 3-Clause	BSD-3-Clause	Permissive, no endorsement

Rule of thumb: MIT or Apache-2.0 for code, CC-BY-4.0 for data/text, CC0-1.0 for maximum reuse.

Zenodo Content Policies (from FAQ)

• ✅ Research data, software, publications, posters, presentations
• ✅ Open data from funded research
• ❌ No military or export-controlled content
• ❌ No purely commercial content without research basis
• ❌ No AI-generated content without verifiable research basis
• ❌ No malware, spam, or illegal content
• ⚠️ Sensitive data must be anonymized or access-restricted

Rate Limits

• Default: 5,000 requests/hour (REST API)
• Authenticated users get higher limits
• OAI-PMH harvesting available for bulk metadata retrieval

File Size Limits

• Per file: 50GB (default, can request increase)
• Per record: 50GB total (default, can request increase)
• For larger deposits: contact Zenodo support before uploading

---

Common Mistakes

Mistake	Fix
Forgetting LICENSE file	Zenodo requires a license. Add one before deposit.
Using .zenodo.json AND CITATION.cff with different data	Keep them in sync, or use only .zenodo.json
Creating a pre-release expecting Zenodo deposit	Use a full release, not pre-release
Hardcoded paths in scripts	Replace with relative paths or here::here() before deposit
Committing large data files	Use .gitignore, link to external data sources
Missing ORCID	Add ORCIDs for all authors — improves discoverability
No keywords	Add 3-5 descriptive keywords for search visibility
Wrong upload_type	software for code, dataset for data — not interchangeable
Publishing sensitive data	Audit for API keys, patient data, credentials before deposit
Not using semantic versioning	Use v1.0.0 format for releases, matches Zenodo expectations