14  Releases and Archiving

14.1 Releases

14.1.1 Changelog

Maintaining a changelog is essential for tracking modifications, fixes, and enhancements in your software. It provides a clear history of changes for current and future users and helps manage versions effectively.

14.1.2 Semantic versioning

Semantic Versioning (SemVer) is a versioning scheme that reflects changes in your software systematically. It consists of three numbers: major, minor, and patch (e.g., 1.9.1).

  • Major version increments are meant for significant changes that may make backward-incompatible changes.
  • Minor version increments add functionality in a backward-compatible manner.
  • Patch version increments are for backward-compatible bug fixes only.

Adopting this practice helps both users and developers anticipate the impact of updating the software. It clearly communicates the nature of the changes.

Release notification

After a release, it’s important to communicate what has changed. Release notes are detailed descriptions of the new changes, fixes, and sometimes known issues. They are usually published alongside the changelog in repositories. You could use GitHub Releases, it is a feature that allows you to present your software, along with the corresponding source code, changelog, and release notes.

Automatically generated release notes

GitHub provides a useful feature to automatically generate release notes for new versions of your software. It scans the commits between your releases and compiles a summary of the changes, fixes, and enhancements made. This can not only save time but also help to avoid undocumenting changes.

How to enable automatic release notes:

  1. Go to your repository on GitHub and navigate to the releases section.
  2. Draft a new release. When you select a tag, GitHub will offer an option to auto-generate the release notes based on the commits since the last release.
  3. Customize the release notes. You can edit the auto-generated content to add more details or format it according to your preferences.
  4. When publishing, the release notes will be attached to your release.

This feature is particularly helpful for maintaining accurate and up-to-date release documentation.

14.2 Archiving

14.2.1 Zenodo

Zenodo is a research data management service that supports the archiving of research outputs, including software releases. Zenodo can automatically archive releases from GitHub repositories and assign a DOI, making each version citable.

To use Zenodo with GitHub:

  1. Link your GitHub account to Zenodo to allow access to repository information.
  2. Enable the repository you want to archive on the Zenodo dashboard.
  3. Create a new release on GitHub. Zenodo will automatically archive this release and issue a DOI.
  4. You can then share the DOI link provided by Zenodo in your project’s README or documentation, or paper, so a specific version of your software can be referenced.
Tips
  • Zenodo can only access public repositories.
  • If you need to archive a repository from an organization, the owner of the organization might have to authorize the Zenodo application to access it.
  • Sandboxing - You can also try out Zenodo Sandbox before archiving your projects to Zenodo. Zenodo Sandbox mimics the main Zenodo platform and is designed to test out the functionality of Zenodo without accidentally making mistakes with the real data and the main site. Since it’s an exact mirror of Zenodo it provides the same user experience and all the same tools and the same interface.
  • Further reading: Referencing and citing content

14.2.2 4TU.ResearchData

4TU.ResearchData is another platform that offers reliable archiving of research data and software. 4TU.ResearchData offers at least 15 years of archival storage.

To get started:

  1. Log in to your 4TU.ResearchData account (using institutional access).
  2. From the dashboard navigate to upload a new project.
  3. Either choose open access or you also have the option to choose embargoed or restricted access.
  4. Upload your relevant files. 4TU.ResearchData supports Git for version control. Either just drag and drop datasets, or to deposit software you can push your Git repository to the 4tu remote. Add the remote:
    • git remote add 4tu [link automatically generated by 4tu] Then, push your repository:
    • git push 4tu --all
    • git push 4tu --tags
  5. You will have a DOI number reserved.
  6. Maintain and update your archive as necessary to reflect any significant changes or additions to the software.
Information
  • When you are ready to publish your software on 4TU.ResearchData, ensure to choose the “Software deposit” option in the Files section at the bottom of the upload form. This option allows you to upload your software files directly from your Git repository. If you have additional files, you can also manually drag your software files from your local drive into the upload box. However, the archiving process is more manual compared to Zenodo, requiring additional steps to upload and manage software releases.
  • 4TU.ResearchData also has a sandbox available.

While both Zenodo and 4TU.ResearchData offer similar archiving capabilities, 4TU.ResearchData is tailored to the needs of data-heavy disciplines, such as secure storage, long-term data preservation, and specific metadata standards that enhance data discoverability and usability. Zenodo might be more suited for easy integration with GitHub and broad accessibility.

Tip

More information on 4TU.ResearchData can be found here.