Tracking metadata#

Every submission in Code Shelf must contain some tracking metadata. This allows users to find out where a notebook or script came from and who to contact in case of problems.

Tracking metadata is not magic!

In notebooks, it is a set of metadata items in the file and in scripts, it is specified in a comment at the top of the script. You can always inspect (or manipulate) the metadata manually without the tools described here.

It is up to the users to not remove or manipulate the metadata unduly.

Metadata fields#

Key	Manual	Description
`authors`	✔	Name and email of the authors. The email is optional.
`version`	✔	Version number of the code using the CalVer format `YY.MM.DD.PATCH`
`commit`		Git commit hash or the source repository
`shelf_url`		URL of the source repository
`original_name`		The name of this file in the source repository
`hash`		A hash of the file including the hash algorithm. The hash is computed in the source repo, i.e., before inserting the final metadata.

When you submit or update a file, you must provide all metadata marked as ‘manual’. All other fields are usually absent in source repositories and get added automatically when code is deployed.

Inspecting metadata#

When you are inside a Code Shelf project, you can use the shelf task to inspect the tracking metadata of a file:

pixi run shelf show path/to/file.ipynb

Alternatively, you can open the file in a text editor and inspect the metadata manually. See the Metadata storage section below.

Checking metadata#

The tracking metadata of every file is checked automatically in GitLab. You can use the following to perform the same check locally:

pixi run shelf check path/to/file.ipynb

or

pixi run shelf check

to check all files in the project.

If these commands print nothing, then the metadata is correct.

Adding / updating metadata#

shelf patch allows you to add tracking metadata if it is missing or update existing metadata:

pixi run shelf patch path/to/file.ipynb

This command is interactive and guides you through the process. It is usually a good idea to inspect the metadata when you are done.

Metadata storage#

Notebooks#

In Jupyter notebooks, tracking metadata is stored in a special "dmsc_tracking" object in the "metadata" object of the notebook’s JSON. For example:

"metadata": {
  "dmsc_tracking": {
    "authors": [
    {
      "email": "sunyoung.yoo@master.coder",
      "name": "Sunyoung Yoo"
    }
  ],
  "version": "25.08.0"
}
}

Additionally, deployed notebooks have an auto-generated cell at the top that summarises the most important fields.

Scripts#

In scripts, tracking metadata is stored using inline script metadata in a [tool.dmsc_tracking] table. For example:

# /// script
# [tool.dmsc_tracking]
# version = "25.09.15.0"
# authors = [{ name: "Harry Baggins", email = "harry.baggins@shire.me" }]
# ///

This Page