GitHub best practices

Documentation and FAIR data

Documentation and FAIR data principles are crucial in research for ensuring transparency, reproducibility, and efficiency. Documentation provides clear records of research processes, while FAIR principles (Findability, Accessibility, Interoperability, Reusability) ensure data is easily shared and used. These practices collectively enhance the integrity and impact of research.

README.md

You can add a README file to your repository to tell other people why your project is useful, what they can do with your project, and how they can use it.

From the GitHub documentation on README files

Materials

• The README file of this course is here.
• README templates and suggestions on https://www.makeareadme.com/.

Questions

• What is .md for a file type?
• What should go into a README file?
• How many README files does one need?

LICENSE.md

Public repositories on GitHub are often used to share open source software. For your repository to truly be open source, you’ll need to license it so that others are free to use, change, and distribute the software.

From the GitHub documentation on licensing a repository

Materials

• Primer on intellectual property righs by the University of Basel’s Research Data Management-Network.
• Choose a license with https://choosealicense.com/.

Questions

• Why do you need a license for research software or research data?
• What are suitable licenses in this context?

CITATION.cff

You can add a CITATION.cff file to the root of a repository to let others know how you would like them to cite your work. The citation file format is plain text with human- and machine-readable citation information.

From the GitHub documentation on CITATION files

Materials

• The CITATION file of this course is here.
• You can youse the cffinit tool to create or update your CITATION file.

Questions

• What is an ORCID ID, what is a DOI?

Releases

GitHub’s way of packaging and providing software to your users.

From GitHub glossary/release

Materials

• The releases of this course are here.
• Releases should adhere to semantic versioning.
• GitHub documentation on releases.

Questions

• What do I put in the release notes?

Zenodo pipeline

GitHub repositories can be published to Zenodo as releases.

Materials

• GitHub documentation on issuing a persistent identifier for your repository with Zenodo-
• A more detailed documentation is here.

CHANGELOG.md

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

From https://keepachangelog.com/en/1.1.0/

Materials

• The CHANGELOG file of this course is here.
• CHANGELOG templates and suggestions on https://keepachangelog.com/en/1.1.0/.

Questions

• Why keep a changelog?
• Who needs a changelog?

GitHub pages

A static site hosting service designed to host your personal, organization, or project pages directly from a GitHub repository.

From GitHub glossary/GitHub pages

Materials

• GitHub pages documentation.
• Guide on how to turn Markdown files in your repo into a website.

Questions

• What’s the advantage of having your documentation on GitHub pages?

Security

Secrets

• login credentials, API keys…

Collaboration

• pull requests
• branch protection
• forking
• issues
• project management tools

Automation

• Documentation on GitHub actions

Getting help

• Documentation (see links below)
• Google is your friend
• Stackoverflow
• GPTs

Useful links

• GitHub glossary
• GitHub documentation
• GitHub Desktop documentation
• GitHub template for FAIR and open research data by Moritz Maehr
• Research Data Management-Network University of Basel