Provision of citation metadata for documentation / reference purposes?

[kevinmatthes]

First of all, merry Christmas! 🎄 🎁 🎉

I would like to suggest the configuration of a CITATION.cff which would be used by GitHub to render a "Cite this repository" blob on the project's landing page. This is useful for users who intended to mention cargo-mutants in their academic publications as well as their own CITATION.cff files as this file format offers an optional list of references. Citations of this project can be considered free advertisement since readers of the papers would learn about cargo-mutants. In addition, the authors section of a CITATION.cff can be also employed as a curated list of contributors whose provision is not uncommon within the open source community.

As I experiment with cargo-mutants as part of the CI of one my projects, at the moment, which I also gave academic presentations for, (at least) I would be interested in being able to cite this project appropriately. I already assisted several projects with the setup of a CITATION.cff, such as Clap and astropy, and I also implemented a set of tools for convenient creation and maintenance experiences of CITATION.cff files, so I am familiar with the necessary changes. At the moment, it is possible to create an entirely self-maintaining CITATION.cff which is updated automatically by GitHub Actions such that no additional overhead would be introduced.

Thus, I would like to ask you if you might be interested in a CITATION.cff, @sourcefrog.

[sourcefrog]

Merry Christmas to you too! Yes, that sounds good.

Please do send a PR.

Also, I'd be interested to see the papers that cite it.

[kevinmatthes]

The entire CFF setup package consists of the following changes:

• the CITATION.cff itself;
• the official CFF validation Action to ensure the validity (usually succeeds within 10 seconds; maintenance-free); and
• some GHA workflows to maintain the CITATION.cff automatically.

For the first point, the basic setup, my documentation assistant Aeruginous yields the following:

abstract: Find inadequately-tested code that can be removed without any tests failing.
authors:
  - name: Martin Pool
cff-version: 1.2.0
keywords:
  - Rust
  - cargo
  - coverage
  - development-tools::testing
  - mutants
  - mutation-testing
  - testing
license: MIT
message: Please cite this project using these information.
repository-code: https://github.com/sourcefrog/cargo-mutants
title: cargo-mutants
url: https://mutants.rs/
version: 23.12.2

The call to Aeruginous, just for completeness:

curl https://raw.githubusercontent.com/sourcefrog/cargo-mutants/main/Cargo.toml | aeruginous mkcff -m rs --suppress-release-date

This basic setup is generated from your Cargo.toml and is a valid starting point. If this base configuration does not need any further customisation, the maintenance is rather straightforward: on release, the CITATION.cff is re-created from the updated Cargo.toml and committed to the repository. If you wish for further adjustments, we would just need to replace the outdated version and update the release date on release; both steps are simple sed commands which can be done within a workflow.

Please tell which adjustments to the data would be required such that I can prepare a PR.

[sourcefrog]

That looks fine. From https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files it seems like it might help to split my name like

authors:
- family-names: "Lisa"
  given-names: "Mona"

[kevinmatthes]

You are correct that CFF allows for splitting names into certain parts, and I will of course adjust this for the PR. I can also add your GitHub username as alias, if you would like. The complete list of possible fields for people is available here: https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#definitionsperson. I can also configure the other contributors as co-authors and / or summarise them anonymously as the "The cargo-mutants Community", for example.

Internally, CFF has a distinction between persons and entities which is mostly defined by the fact that people usually have names consisting of parts whereas entities only have one rigid, proper name which cannot be decomposed. Thus, Aeruginous by design tends to define entities instead of people. The reason why it does not try to split names into parts is that, as discussed in citation-file-format/citation-file-format#329, there is a problem with name composition from these parts as several regional conventions are not respected. The easiest solution would be to also specify an assembly pattern to handle the name composition appropriately. The other way around, when it comes to name detection, the more important problem is to decompose the name into the possible parts correctly. It would require some statistical approach to properly split the name into the parts but even this partial solution might fail, for example if an actual given name might be also a family name or the name is an artistic name consisting of multiple words. Since the order of a name's parts can be furthermore considered an integral aspect of how the respective person intends to be addressed -- there are also laws about this aspect --, Aeruginous was designed to do not try to decompose any name in order to respect both regional conventions as well as a person's explicit wish how to be referred. If you have an idea how to appropriately perform the name splitting, please feel free to suggest it: https://github.com/kevinmatthes/aeruginous-rs/issues/new; https://github.com/kevinmatthes/aeruginous-rs/discussions/new?category=ideas.

[kevinmatthes]

The PR is submitted as #212.

[kevinmatthes]

#212 is merged, so I will mark this discussion as resolved.