Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Zenodo DOI Guide for REMARKs

Complete step-by-step guide for obtaining a permanent Zenodo DOI for your REMARK

For Published REMARKs (Tier 3), a permanent Zenodo DOI is required. Obtain your Zenodo DOI only after your REMARK is otherwise complete—it should be the very last thing you do before submitting your REMARK for incorporation into the Econ-ARK ecosystem. That way the archived version matches exactly what you submit. This guide walks you through the process.


Table of Contents

  1. Prerequisites

  2. Quick Checklist

  3. Detailed Step-by-Step Instructions

  4. Troubleshooting

  5. Verification

  6. FAQ


Prerequisites

Before starting, ensure you have:


Quick Checklist

Use this checklist to track your progress:

Phase 1: Pre-Flight (5 minutes)

Phase 2: Git Tagging (2 minutes)

Phase 3: Zenodo Setup (5-10 minutes)

Phase 4: GitHub Release (2 minutes)

Phase 5: Zenodo Archival (5-10 minutes)

Phase 6: Update CITATION.cff (2 minutes)

Phase 7: Verification (5 minutes)

Total Time: 30-45 minutes


Detailed Step-by-Step Instructions

Step 1: Pre-Flight Checks (5 minutes)

1.1 Verify Repository is Clean

cd /path/to/your-remark
git status

Expected output: nothing to commit, working tree clean

If you see uncommitted changes, commit them first:

git add .
git commit -m "Prepare for v1.0.0 release"
git push origin main  # or master

1.2 Verify CITATION.cff

Check that your CITATION.cff has all required fields:

cat CITATION.cff

Required fields:

Helpful but not required:

1.3 Test Reproduction Script

./reproduce.sh --help

Should display help information without errors.

1.4 Verify Required Files

ls -la reproduce.sh CITATION.cff binder/environment.yml LICENSE

All should exist and be readable.


Step 2: Create Git Tag (2 minutes)

2.1 Create Annotated Tag

Choose a version number following semantic versioning:

git tag -a v1.0.0 -m "First published release"

Verify tag was created:

git tag -l
git show v1.0.0

2.2 Push Tag to GitHub

git push origin v1.0.0

Verify on GitHub:


Step 3: Enable Zenodo-GitHub Integration (5-10 minutes)

3.1 Log in to Zenodo

  1. Go to https://zenodo.org

  2. Click “Log in” (top right)

  3. Select “Log in with GitHub”

  4. Authorize Zenodo if prompted

3.2 Navigate to GitHub Settings

  1. Click your username (top right)

  2. Select “GitHub” from dropdown menu

  3. This opens: https://zenodo.org/account/settings/github/

3.3 Grant Repository Access

If this is your first time using Zenodo:

  1. You’ll see a message: “Authorize application access on GitHub”

  2. Click the link to GitHub settings

  3. On GitHub, find “Zenodo” in Applications

  4. Click “Configure”

  5. Under “Repository access”:

    • Select “Only select repositories”

    • Choose your REMARK repository

  6. Click “Save”

Return to Zenodo and refresh the GitHub settings page.

3.4 Enable Your Repository

On the Zenodo GitHub settings page:

  1. Find your repository in the list

  2. Toggle the switch to ON (green)

  3. If you don’t see your repository, click “Sync now”

Common issues:


Step 4: Create GitHub Release (2 minutes)

4.1 Navigate to Releases

Go to: https://github.com/YOUR_USERNAME/YOUR_REMARK/releases

4.2 Draft New Release

  1. Click “Draft a new release” button

4.3 Fill in Release Details

Choose a tag: Select v1.0.0 from dropdown

Release title: Use a clear, descriptive title

Description: Include key information (example):

## Version 1.0.0 - Initial Published Release

This release accompanies the submission to [Journal Name].

### What's Included
- Complete replication package
- All data and code
- Comprehensive documentation
- Automated reproduction workflow

### System Requirements
- See `binder/environment.yml` for dependencies
- Reproduction time: ~X minutes on standard laptop

### Citation
See CITATION.cff for bibliographic information.

### License
Apache License 2.0

4.4 Publish Release

  1. Leave “This is a pre-release” unchecked

  2. Click “Publish release”

Verification:


Step 5: Obtain Zenodo DOI (5-10 minutes)

5.1 Wait for Zenodo Archival

Zenodo automatically archives your release when you publish it.

Timeline:

Monitoring:

  1. Go to Zenodo uploads: https://zenodo.org/deposit

  2. Look for your repository name

  3. Status will show “Processing...” then “Published”

Alternative: Check your email for Zenodo notification

5.2 Find Your Upload

  1. Go to: https://zenodo.org/deposit

  2. Click on your REMARK name

  3. This opens the Zenodo landing page

Or navigate directly (after it’s published):

5.3 Obtain the DOI

On the Zenodo landing page:

  1. DOI badge: At top right of page

  2. DOI format: 10.5281/zenodo.XXXXXXX (7-digit number)

Copy the DOI number (just the number, e.g., 10.5281/zenodo.1234567)

5.4 Get DOI Badge Markdown

On the same Zenodo page:

  1. Look for “DOI” badge (top right)

  2. Click the badge

  3. Select “Markdown” format

  4. Copy the code, which looks like:

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1234567.svg)](https://doi.org/10.5281/zenodo.1234567)

Step 6: Update CITATION.cff (2 minutes)

6.1 Add DOI to CITATION.cff

Edit your CITATION.cff file and add the DOI:

cff-version: 1.2.0
title: "Your REMARK Title"
authors:
  - family-names: "Smith"
    given-names: "John"
repository-code: 'https://github.com/YOUR_USERNAME/YOUR_REMARK'
doi: 10.5281/zenodo.1234567  # ADD THIS LINE
license: Apache-2.0
keywords:
  - REMARK
  - Reproducibility

Important:

6.2 Commit and Push

git add CITATION.cff
git commit -m "Add Zenodo DOI to CITATION.cff

DOI: 10.5281/zenodo.XXXXXXX
Archive: https://doi.org/10.5281/zenodo.XXXXXXX

Published REMARK complete."

git push origin main  # or master

6.3 Optional: Add DOI Badge to README

Edit your README.md and add the badge at the top:

# Your REMARK Title

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1234567.svg)](https://doi.org/10.5281/zenodo.1234567)

[Rest of README...]

Step 7: Verification (5 minutes)

7.1 Download Archive from Zenodo

Test that anyone can download your archive:

# Get download URL from Zenodo page, then:
cd /tmp
curl -L -O "https://zenodo.org/records/XXXXXXX/files/YOUR_USERNAME-YOUR_REMARK-YYYYYYY.zip"

7.2 Verify Archive Contents

unzip YOUR_USERNAME-YOUR_REMARK-YYYYYYY.zip
cd YOUR_USERNAME-YOUR_REMARK-YYYYYYY
ls -la

Check for:

7.3 Test Basic Functionality

./reproduce.sh --help

Should display help without errors.

7.4 Verify Commit Hash Matches

# In the Zenodo download directory:
git rev-parse HEAD

# In your original repository:
cd /path/to/your-remark
git rev-parse v1.0.0

Both should show the same commit hash - this is cryptographic proof they’re identical.


Troubleshooting

Problem: Repository Not Appearing on Zenodo

Symptoms: Your repository doesn’t appear in Zenodo’s GitHub settings page

Solutions:

  1. Click “Sync now” on Zenodo GitHub settings page

    • Wait 30-60 seconds

    • Refresh page

  2. Check GitHub authorization:

  3. Check repository is public:

    • Zenodo cannot access private repositories

    • Go to repository settings on GitHub

    • Under “Danger Zone”, ensure it’s public

  4. Check organization permissions (if applicable):

    • Organization settings → Third-party access

    • Ensure Zenodo is authorized

    • Grant access to repositories

Problem: Release Created but No Zenodo Archive

Symptoms: GitHub release exists, but no Zenodo archive created

Solutions:

  1. Verify Zenodo toggle is ON:

  2. Check release is not a “pre-release”:

    • Pre-releases don’t trigger Zenodo archival

    • Edit release on GitHub

    • Uncheck “This is a pre-release”

  3. Wait longer:

    • Large repositories take longer to archive

    • Check back in 15-30 minutes

  4. Create a new release:

    • Sometimes the webhook fails

    • Create a new tag: v1.0.1

    • Create a new release

    • Should trigger archival

Problem: DOI Badge Not Showing on GitHub

Symptoms: Added DOI to CITATION.cff but badge doesn’t appear

Solutions:

  1. Verify CITATION.cff syntax:

    # Validate YAML syntax
    python -c "import yaml; yaml.safe_load(open('CITATION.cff'))"
  2. Check DOI format:

    • Correct: doi: 10.5281/zenodo.1234567

    • Incorrect: doi: https://doi.org/10.5281/zenodo.1234567

  3. Wait for GitHub cache:

    • GitHub caches CITATION.cff

    • Wait 5-10 minutes

    • Hard refresh browser (Ctrl+F5 or Cmd+Shift+R)

Problem: Archive Missing Files

Symptoms: Downloaded Zenodo archive is incomplete

Solutions:

  1. Check .gitignore:

    • Files in .gitignore won’t be archived

    • Review and update .gitignore

    • Create new tag and release

  2. Verify files were committed:

    git ls-tree -r v1.0.0 --name-only
    • This shows all files in the tag

  3. Large files:

    • GitHub releases have file size limits

    • Consider data download instructions instead

    • Use Git LFS for large files


Verification Checklist

After completing all steps, verify:

On GitHub

On Zenodo

Cryptographic Verification

Documentation


FAQ

Q: Do I need to create a new DOI for every version?

A: No. Zenodo automatically creates version-specific DOIs, but all versions share a “concept DOI” that always points to the latest version. You can use either:

For Published REMARKs, use the version-specific DOI in CITATION.cff.

Q: What version number should I use?

A: Follow semantic versioning:

Q: Can I delete a Zenodo upload?

A: No. Zenodo is a permanent archive. However, you can:

Plan carefully before creating releases.

Q: How long does Zenodo preserve data?

A: Minimum 20 years, but likely indefinitely. Zenodo is operated by CERN and has long-term preservation commitments.

Q: What if my repository changes after archival?

A: The Zenodo archive is frozen at the tagged commit. Your repository can continue to evolve. Create new releases/tags for updated versions.

Q: Do I need Zenodo for Standard REMARKs?

A: No. Zenodo DOI is only required for Published REMARKs. Standard REMARKs can be submitted without a DOI.

Q: When should I obtain my Zenodo DOI?

A: Only after your REMARK fully meets all other Tier 3 requirements (reproduce.sh works, documentation complete, tagged release, etc.). Obtaining the Zenodo DOI should be the very last thing you do before submitting your REMARK for incorporation into the Econ-ARK ecosystem—so the archived version matches exactly what you submit.

Q: Can I use a different archive service?

A: Zenodo is preferred for REMARKs because:

Other services (Figshare, OSF) can work but require manual steps.

Q: What’s the difference between the econ-ark fork and Zenodo?

A:

Q: How do I cite a Zenodo-archived REMARK?

A: The CITATION.cff provides the format. Generally:

AuthorLastName, F. (YEAR). Title of REMARK.
https://doi.org/10.5281/zenodo.XXXXXXX

Example: Complete Workflow

Here’s a complete example walkthrough:

# Step 1: Verify repository is ready
cd ~/my-remark
git status  # Should be clean

# Step 2: Create tag
git tag -a v1.0.0 -m "First published release"
git push origin v1.0.0

# Step 3: Go to Zenodo (via browser)
# - Log in at https://zenodo.org
# - Enable GitHub integration
# - Toggle on your repository

# Step 4: Create GitHub release (via browser)
# - Go to github.com/yourname/your-remark/releases
# - Click "Draft a new release"
# - Select tag v1.0.0
# - Add title: "Version 1.0.0 - Initial Release"
# - Publish

# Step 5: Wait for Zenodo archival (2-10 minutes)
# Check: https://zenodo.org/deposit

# Step 6: Update CITATION.cff with DOI
echo "doi: 10.5281/zenodo.1234567" >> CITATION.cff
git add CITATION.cff
git commit -m "Add Zenodo DOI"
git push

# Step 7: Verify
curl -L -O "https://zenodo.org/records/1234567/files/archive.zip"
unzip archive.zip
cd yourname-your-remark-abc1234
./reproduce.sh --help  # Should work

Total time: 30-45 minutes from start to finish.


Additional Resources

Official Documentation

Tools

REMARK Resources


Summary

Quick Reference Command Sequence

# 1. Create tag
git tag -a v1.0.0 -m "Published release"
git push origin v1.0.0

# 2. Enable on Zenodo (browser): https://zenodo.org/account/settings/github/

# 3. Create GitHub release (browser): github.com/you/repo/releases

# 4. Wait for Zenodo archival

# 5. Add DOI to CITATION.cff
# Edit CITATION.cff, add line: doi: 10.5281/zenodo.XXXXXXX

# 6. Commit and push
git add CITATION.cff
git commit -m "Add Zenodo DOI"
git push

# Done!

Timeline

PhaseDurationActivity
Pre-flight5 minVerify repository ready
Tagging2 minCreate and push git tag
Zenodo setup5-10 minEnable integration (first time only)
Release2 minCreate GitHub release
Archival5-10 minWait for Zenodo processing
Update2 minAdd DOI to CITATION.cff
Verification5 minDownload and test archive
Total30-45 minComplete workflow

Getting Help

If you encounter issues not covered in this guide:

  1. Check Zenodo documentation: https://help.zenodo.org/

  2. Search existing issues: https://github.com/econ-ark/REMARK/issues

  3. Open a new issue: https://github.com/econ-ark/REMARK/issues/new

  4. Contact REMARK maintainers: Via GitHub issues


Document Version: 1.0
Last Updated: December 2025
Maintained by: econ-ark REMARK team