Maintaining author metadata#

The list of authors for a technote is maintained in the technote.toml file. This page describes how to add and update author listings.

The connection to authordb.yaml#

The author metadata in a technote’s technote.toml file is derived from Rubin Observatory’s author database, authordb.yaml, located in the lsst/lsst-texmf repository. The internal_id field in technote.toml points to the author’s entry in authordb.yaml. This is done so that team members are identified consistently across Rubin Observatory documents and publications.

For example, an author with an ID of sickj is represented in technote.toml as:

technote.toml#

[[technote.authors]]
name = {given = "Jonathan", family = "Sick"}
internal_id = "sickj"
orcid = "https://orcid.org/0000-0003-3001-676X"
[[technote.authors.affiliations]]
name = "Rubin Observatory Project Office"
internal_id = "RubinObs"
address = "950 N. Cherry Ave., Tucson, AZ 85719, USA"

The corresponding entry in authordb.yaml is:

authordb.yaml in lsst/lsst-texmf#

authors:
  # [...]
  sickj:
    affil:
    - RubinObs
    altaffil: []
    initials: Jonathan
    name: Sick
    orcid: 0000-0003-3001-676X

The highlighted lines, above, show the author ID that connects these metadata sets.

A consequence of this connection is that all technote authors must have an entry in authordb.yaml. You can add and update entries by submitting a pull request to the lsst/lsst-texmf repository.

Adding a new author#

Given an author ID from authordb.yaml, you can add that author to the technote’s metadata by running the make add-author command:

make add-author

That command prompts you for the author ID, and then appends the author to the end of the author listing in technote.toml (existing authors are updated in place).

If you know the author’s ORCID but not their author ID, identify them with the --orcid option of the underlying documenteer technote add-author command instead:

documenteer technote add-author --orcid 0000-0003-3001-676X

ORCIDs are globally unique, so this looks the author up exactly, where a name can be spelled several ways. Write the ORCID either bare, as above, or as an https://orcid.org/ URL. The author still needs an entry in authordb.yaml that records that ORCID; if no entry does, the command says so and leaves technote.toml unchanged.

Authors are represented in technote.toml as as individual tables under the technote.authors array of tables. A technote with Sick as the first author and Economou as the second author would look like:

technote.toml#

[[technote.authors]]
name = {given = "Jonathan", family = "Sick"}
internal_id = "sickj"
orcid = "https://orcid.org/0000-0003-3001-676X"
[[technote.authors.affiliations]]
name = "Rubin Observatory Project Office"
internal_id = "RubinObs"
address = "950 N. Cherry Ave., Tucson, AZ 85719, USA"

[[technote.authors]]
name = {given = "Frossie", family = "Economou"}
internal_id = "economouf"
orcid = "https://orcid.org/0000-0002-8333-7615"
[[technote.authors.affiliations]]
name = "Rubin Observatory Project Office"
internal_id = "RubinObs"
address = "950 N. Cherry Ave., Tucson, AZ 85719, USA"

To change the order of authors, you can move the [[technote.authors]] tables around in the file. Don’t forget to keep the [[technote.authors.affiliations]] tables with their corresponding authors.

Updating author metadata#

Occasionally the author metadata in authordb.yaml will change. To update the author metadata in your technote, run:

make sync-authors

Each [[technote.authors]] entry is looked up by its internal_id and rewritten from the database.

Repairing an author ID#

An entry whose internal_id is wrong, or missing altogether, is repaired from the orcid the entry declares. ORCIDs are globally unique, so the lookup identifies the author exactly, and the command writes the right ID into that entry — it does not add a second one. The report says so, and names the ID it replaced:

Synchronized authors to technote.toml:
- R. Lynne Jones (lynnej → jonesrl, matched by ORCID)
- Yusra AlSayyad (alsayyady, matched by ORCID)
- Jonathan Sick (sickj)

This is the fix for TN101 and TN102 findings on an author who declares an ORCID: run make sync-authors rather than editing the ID by hand.

One repair the command will not make for you is one that would list the same author twice. If the ID an entry’s ORCID resolves to is already declared by another entry — the same person listed once under the right ID and once under a wrong one — the entry is reported as a warning and left as you declared it, because only you can say which of the two entries is the duplicate to drop:

Warning: Could not sync author Lynne Jones: their ORCID resolves to internal_id 'jonesrl', which another author entry already declares. Remove whichever of the two entries is the duplicate.

An author who resolves to nobody at all — no usable internal_id and no orcid that the author database knows — is reported as a warning and left exactly as you declared them:

Warning: Could not sync author No Body: internal_id 'nobody' is not in the Rubin author database, and the entry declares no ORCID to fall back on.

Every other author is still synchronized and written, so one unknown author no longer costs the rest their update. The command exits non-zero, so a CI job still fails on it. Fix such an author by adding them to authordb.yaml, or by correcting the internal_id or orcid in technote.toml.

Maintaining author metadata#

The connection to authordb.yaml#

Adding a new author#

Updating author metadata#

Repairing an author ID#

Related documentation#