GitHub template for FAIR and open research data

This GitHub template is independent of the (research) data and its format. It follows the best practices for open research data as outlined in The Turing Way. It uses GitHub Actions to manage releases, issues, and pull requests, GitHub Pages for documentation, and Zenodo for long-term archiving.

Why use a template (even for small datasets)?

• Share your open research data with others
• Write better documentation for yourself and the community
• Write more consistent code and encourage collaboration
• Increase security
• Follow accepted ethics

How this template helps you

Open research data

• Citeable via DOI (and CITATION.cff)
• Automatic long-term archiving via Zenodo
• Licensed under a non-restrictive AGPL 3.0 and CC BY 4.0 license according to The Turing Way
• Templates for reporting data issues using a custom template github/ISSUE_TEMPLATE/data_issue_report.yml

Documentation

• README.md according to www.makeareadme.com and The Turing Way
• CHANGELOG.md according to keepachangelog.com
• Automated CHANGELOG.md via git-cliff
• package.json via npm docs
• Accessible documentation via gh-pages and Quarto

Consistency

• Consistent formatting via Prettier
• Consistent commit messages according to Conventional Commits via husky
• Consistent versioning via Semantic Versioning
• Consistent fork and pull workflow via GitHub branch protection
• Consistent issues via issue templates
• Consistent file and folder naming conventions via The Turing Way

Security

• SECURITY.md per GitHub
• GitHub Security Alerts
• Integrity via GitHub branch protection

Ethics

• CODE_OF_CONDUCT.md per the Contributor Covenant
• Friendly initial interactions via Greetings

Installation

We recommend using GitHub Codespaces for a reproducible setup.

Getting Started

For Most Users: Reproducible Setup with GitHub Codespaces

1. Use this template for your project in a new repository on your GitHub account.

   

2. Click the green <> Code button at the top right of this repository.

3. Select the “Codespaces” tab and click “Create codespace on main”. GitHub will now build a container that includes:

   • ✅ Node.js (via npm)
   • ✅ Python with uv
   • ✅ R with renv
   • ✅ Quarto
   

4. Once the Codespace is ready, open a terminal and preview the documentation:

   uv run quarto preview

   

Note: All dependencies (Node.js, Python, R, Quarto) are pre-installed in the Codespace.

👩‍💻 Advanced Local Installation

Prerequisites

• Node.js
• R and Rtools (on Windows)
• uv (Python manager)
• Quarto

Note: uv installs and manages the correct Python version automatically.

Local Setup Steps

# 1. Install Node.js dependencies
npm install
npm run prepare

# 2. Setup Python environment
uv sync

# 3. Setup R environment
Rscript -e 'install.packages("renv"); renv::restore()'

# 4. Preview documentation
uv run quarto preview

Project Setup Checklist (for all users)

After creating your project from this template (either via Codespaces or local setup), complete the following steps to customize and finalize your project:

• Enable GitHub Security Alerts: Go to your repository's "Security" tab on GitHub and enable security alerts.
• Protect the Main Branch: In your repository settings on GitHub (under "Branches"), protect your main branch.
• Update Project Details: Replace placeholders like FULLNAME, USERNAME, REPO_NAME, SHORT_DESCRIPTION, and [INSERT CONTACT METHOD] in .github/ISSUE_TEMPLATE/config.yml, _brand.yml, CODE_OF_CONDUCT.md, package.json, README.template.md, and SECURITY.md.
• Set Up Zenodo Integration: Follow the Zenodo guide to connect your repository to Zenodo for long-term archiving and to get a DOI.
• Set Up Zenodo DOI Badge: Replace GITHUB_REPO_ID with idfrom https://api.github.com/repos/USERNAME/REPO_NAME. This will automatically update with your Zenodo DOI once you make a release.
• Add Zenodo DOI to README: Once you have your Zenodo DOI, add it to the README.md file by replacing ZENODO_RECORD.
• Add Favicons: Add favicons to the root directory (see favicon.io).
• Address TODOs: Search for TODO comments throughout the project files and complete the tasks.
• Finalize README: Delete this README.md and rename README.template.md to README.md.
• Format Files: Run npm run format to ensure all files are formatted.
• Commit Changes: Run npm run commit to save your changes with a standardized commit message.
• Generate Changelog: Run npm run changelog and copy the output into the CHANGELOG.md file.
• Customize Documentation: Customize your documentation using Quarto's features.
• Enable GitHub Pages: In your repository settings on GitHub (under "Pages"), configure GitHub Pages to publish from the gh-pages branch.
• Publish Documentation: Run quarto publish gh-pages to publish your documentation website.

Optional:

• Add Citation File: Create a CITATION.CFF file (see citation-file-format.github.io).
• Add Zenodo Metadata File: Create a .zenodo.json file for Zenodo metadata (Zenodo developer docs).

Use

Check that all files are properly formatted.

npm run check

Format all files.

npm run format

Run the wizard to write meaningful commit messages.

npm run commit

Run the wizard to create a CHANGELOG.md.

npm run changelog

Preview the documentation.

quarto preview

Support

This project is maintained by @maehr. Please understand that we can't provide individual support via email. We also believe that help is much more valuable when it's shared publicly, so more people can benefit from it.

Type	Platforms
🚨 Bug Reports	GitHub Issue Tracker
📊 Report bad data	GitHub Issue Tracker
📚 Docs Issue	GitHub Issue Tracker
🎁 Feature Requests	GitHub Issue Tracker
🛡 Report a security vulnerability	See SECURITY.md
💬 General Questions	GitHub Discussions

Roadmap

There are currently no changes planned.

Contributing

Please see CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Authors and credits

• Moritz Mähr - Initial work - maehr
• Moritz Twente - Enhancements - moritztwente

See also the list of contributors who contributed to this project.

License

The data in this repository is released under the Creative Commons Attribution 4.0 International (CC BY 4.0) License - see the LICENSE-CCBY file for details. By using this data, you agree to give appropriate credit to the original author(s) and to indicate if any modifications have been made.

The code in this repository is released under the GNU Affero General Public License v3.0 - see the LICENSE-AGPL file for details. By using this code, you agree to make any modifications available under the same license.