GitHub

ResearchSoftwareMetadata documentation

Documentation for ResearchSoftwareMetadata.

Summary

ResearchSoftwareMetadata is a Julia package that provides functionality for to allow a crosswalk between Project.toml, codemeta.json, .zenodo.json and the package LICENSE file to allow a consistent way of providing metadata for research software which allows the Julia General Registry to pick up the same metadata as GitHub and Zenodo while following the Research Software MetaData guidelines.

Installation

The package is registered in the General registry so can be built and installed with add. For example:

(@v1.10) pkg> add ResearchSoftwareMetadata
   Resolving package versions...
    Updating `~/.julia/environments/v1.10/Project.toml`
  [aea672f4] + ResearchSoftwareMetadata v0.1.0
    Updating `~/.julia/environments/v1.10/Manifest.toml`

(@v1.10) pkg>

Usage

First you need to add a small amount of additional metadata into your Project.toml file.

To capture the license you are using and propagate it throughout the metadata files and through your julia code, add an SPDX license identifier to the file:

[license]
SPDX = "BSD-2-Clause"

To supplement the metadata on the authors of the package, add the ORCID for each author and the ROR for the organisation(s) they are affiliated with. You can add as many authors and as much or as little information as you like about each one by adding additional [[author_details]] blocks.

[[author_details]]
name = "Richard Reeve"
orcid = "0000-0003-2589-8091"

    [[author_details.affiliation]]
    ror = "00vtgdb53"

Then, from the root of your package, you can just run a crosswalk:

using Pkg

# Create a new project with ResearchSoftwareMetadata in it
Pkg.activate(; temp = true)
Pkg.add("ResearchSoftwareMetadata")

# Carry out a crosswalk between the different metadata formats
using ResearchSoftwareMetadata
ResearchSoftwareMetadata.crosswalk()

If you want to add in some additional metadata (the category of the software, or the keywords associated with it, or you want to increase the package version during the crosswalk, this is possible as follows:

# Add in additional metadata
ResearchSoftwareMetadata.crosswalk(category = "ecology", keywords = ["julia", "metadata", "research software", "RSMD"])

# Increase version number during crosswalk
ResearchSoftwareMetadata.increase_patch() # Bump patch version (e.g. 0.4.1 -> 0.4.2)
ResearchSoftwareMetadata.increase_minor() # Bump minor version (e.g. 0.4.1 -> 0.5.0)
ResearchSoftwareMetadata.increase_major() # Bump major version (e.g. 0.4.1 -> 1.0.0)

You might also consider reformatting all of your julia code to a consistent format. A .JuliaJormatter.toml file in the package root defines what the formatting standard should be.

Pkg.add("JuliaFormatter")
Pkg.develop("MyPackage")
using JuliaFormatter
using MyPackage
format(MyPackage)

Reference guide

ResearchSoftwareMetadata.crosswalk — Function
ResearchSoftwareMetadata.crosswalk(; category = nothing, keywords = nothing, build = false)

Runs a crosswalk across Project.toml, LICENSE, codemeta.json and .zenodo.json as well as the julia source files to enforce consistency between the different metadata formats. It logs warnings and errors if it identifies inconsistencies while it is editing the files. The software category can be set with the category argument, likewise the keywords argument can contain a vector of keyword strings. The build argument sets the buildInstructions RSMD field - false leaves the instructions as is, true sets it to the same as the README, and a string sets it to that value. If update is true, mismatches between version numbers in codemeta.json are accepted.

source
ResearchSoftwareMetadata.get_os_from_workflows — Function
ResearchSoftwareMetadata.get_os_from_workflows()

Returns the operating systems that the GitHub workflows associated with this package work on. This is presumed to represent the operating systems that the software runs on.

source
ResearchSoftwareMetadata.get_person_from_orcid — Method
ResearchSoftwareMetadata.get_person_from_orcid(orcid::String)

Take an ORCID from the user and query the orcid.org API to return a Dict containing the relevant metadata or nothing if no such ORCID exists.

source
ResearchSoftwareMetadata.increase_major — Function
ResearchSoftwareMetadata.increase_major()

Increases the Project.toml version number by a major number (e.g. 0.4.1 to 1.0.0), and then runs ResearchSoftwareMetadata.crosswalk() to propagate this information.

source
ResearchSoftwareMetadata.increase_minor — Function
ResearchSoftwareMetadata.increase_minor()

Increases the Project.toml version number by a minor number (e.g. 0.4.1 to 0.5.0), and then runs ResearchSoftwareMetadata.crosswalk() to propagate this information.

source
ResearchSoftwareMetadata.increase_patch — Function
ResearchSoftwareMetadata.increase_patch()

Increases the Project.toml version number by a patch (e.g. 0.4.1 to 0.4.2), and then runs ResearchSoftwareMetadata.crosswalk() to propagate this information.

source