maehr/open-research-data-template

GitHub template for FAIR and open research data

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

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

To initialize the template, generate a new project, clone the repository to your local machine and follow this guide.

1. Install Node.js and run the following commands in the root directory of the repository:

npm install
npm run prepare

2. Complete the following checklist of tasks to customize the template for your project:

• enable GitHub security alerts
• protect the main branch to enforce a fork and pull workflow
• search and replace FULLNAME, USERNAME, REPO_NAME, SHORT_DESCRIPTION [INSERT CONTACT METHOD] in CODE_OF_CONDUCT.md, package.json, README.template.md, SECURITY.md
• setup the Zenodo integration
• add ZENODO_RECORD to README.md
• add favicons to ./, e.g. via favicon.io
• search for TODO in the project (mostly documentation) and fix it
• delete README.md
• rename README.template.md to README.md
• run npm run format to format all files
• run npm run commit to commit all changes
• run npm run changelog and include the output in CHANGELOG.md
• install Quarto
• run quarto publish gh-pages to publish the documentation
• customize the documentation with Quarto
• enable gh-pages for the gh-pages branch

3. optional tasks:

• add a CITATION.CFF according to citation-file-format.github.io
• add a .zenodo.json according to zenodo.org

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

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.