Guide: Creating Stable Citations for EnvisionBOX Modules

This guide walks you through the process of creating a permanent, citable reference for your coding modules using GitHub and Zenodo. By following these steps, you will generate a DOI (Digital Object Identifier) that ensures your work is recognized in academic research.

Prerequisites

• A public GitHub repository for your module.
• "Write" or "Maintainer" access to the repository.
• A Zenodo account (Log in using your GitHub account).

Step 1: Add a CITATION.cff File

The CITATION.cff is a plain-text file that tells GitHub and Zenodo exactly how to format the citation.

1. In the root of your GitHub repository, create a new file named CITATION.cff.
2. Copy and paste the template below, replacing the placeholders with your module's information:

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
  - family-names: "Lastname"
    given-names: "Firstname"
  - family-names: "CollaboratorLastname"
    given-names: "CollaboratorFirstname"
title: "Title of Your Module"
version: 1.0.0
date-released: yyyy-mm-dd
url: "https://envisionbox.org/your_module_page.html"
repository-code: "https://github.com/YourUser/YourRepo"
type: software

Step 2: Enable Zenodo Integration

Zenodo needs permission to "watch" your repository for new releases.

1. Log in to Zenodo with your GitHub account.
2. Go to [Your Profile (top right)] > GitHub.
3. Click "Sync now" to refresh your repository list.
4. Find your module's repository and toggle the switch to "ON".

Step 3: Trigger the Zenodo DOI (Create a Release)

Zenodo only archives your code and issues a DOI when you create an official Release on GitHub.

1. On your GitHub repository page, click "Create a new release" (found in the right-hand sidebar).
2. Tag version: E.g., v1.0.0. (Mandatory)
3. Release title: E.g., Initial Release for EnvisionBox. (Mandatory)
4. Click Publish release.

Step 4: Get Your Zenodo DOI Badge

Within 1–2 minutes of your release, Zenodo will archive the code.

1. Go to your Zenodo Uploads page.
2. Click on your repository entry.
3. Locate the DOI Badge (the blue image) on the right.
4. Copy the Markdown code for this DOI Badge.

Step 5: Add the DOI Badge to your GitHub README

In your GitHub README.md, add a citation section:

## Citation
> First Name, Last Name. (year). Module Name (Version X.X.X). Zenodo. https://doi.org/10.5281/zenodo.xxxxxxx

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

Step 6: Update the EnvisionBox Website

Add the formal citation to the HTML file of your module. If you do not have editing access, please contact a core member.

<p><strong>To cite this module:</strong></p>
<ul class="bulleted-list">
  <li>
    Lastname, F., & Collaborator, F. (2024). 
    <em>Title of Your Module (Version 1.0.0).</em> 
    Zenodo. 
    <a href="https://doi.org/10.5281/zenodo.XXXXXXXX" target="_blank" rel="noopener noreferrer">
      https://doi.org/10.5281/zenodo.XXXXXXXX
    </a>
  </li>
</ul>

FAQ