Keep CITATION and citation.cff in sync with DESCRIPTION

[jamesmbaazam]

This PR closes #466 by adding a GitHub Actions workflow to auto-generate citation.cff whenever the citation fields in CITATION and DESCRIPTION change. It also adds code to keep inst/CITATION and DESCRIPTION in sync. Together, this will ensure that the package citation information is always up to date.

[seabbs]

So this PR would add a CITATION.cff file but it wouldn't help with updating the current CITATION file? As far as I know there is no way currently to use a cff to update a CITATION file so it gets picked up properly by R?

This action would also ideally update the README as the citation is printed there.

[jamesmbaazam]

As far as I know there is no way currently to use a cff to update a CITATION file so it gets picked up properly by R?

cffr::write_citation() can create the CITATION file from citation.cff. So, maybe, we can modify this workflow to recreate CITATION every time it creates citation.cff.

This action would also ideally update the README as the citation is printed there.

I don't see the citation info in the README 👀.

[Bisaloo]

So this PR would add a CITATION.cff file but it wouldn't help with updating the current CITATION file? As far as I know there is no way currently to use a cff to update a CITATION file so it gets picked up properly by R?

It's the other way around. CITATION is the source of truth, and its contents will be used to generate CITATION.cff. If both CITATION and CITATION.cff are auto-generated, what is the source of truth for data such as the doi?

If you want to keep CITATION in sync with DESCRIPTION, it can be achieved through standard R mechanisms, without the need for an external package & workflow. Try this as the contents of CITATION:

# Code copied from citation()
author <- meta$`Authors@R`
if (length(author)) {
    aar <- .read_authors_at_R_field(author)
    author <- Filter(function(e) {
        !(is.null(e$given) && is.null(e$family)) && !is.na(match("aut", 
            e$role))
    }, aar)
}

bibentry(
  bibtype = "Manual",
  title   = paste0(meta$Package, ": ", gsub("[[:space:]]+", " ", meta$Title)),
  author  = author,
  year    = format(meta$Date, "%Y"),
  doi     = "10.5281/zenodo.3957489"
)

[seabbs]

Thanks @Bisaloo 🙏🏻

[jamesmbaazam]

If you want to keep CITATION in sync with DESCRIPTION, it can be achieved through standard R mechanisms, without the need for an external package & workflow. Try this as the contents of CITATION.

Thanks, @Bisaloo. So, if I'm getting you right, a full-proof mechanism will involve adding the code snippet above to CITATION along with the workflow in this PR?

[Bisaloo]

So, if I'm getting you right, a full-proof mechanism will involve adding the code snippet above to CITATION along with the workflow in this PR?

If you want automatic sync of CITATION and CITATION.cff based on DESCRIPTION, yes.

• the code provided for CITATION will ensure that CITATION data is pulled at package-building time from DESCRIPTION
• the GHA workflow will re-generate CITATION.cff from DESCRIPTION and CITATION any time one of these two files is updated

[seabbs]

So I think this can be merged once it is unlinked from the current issue it is linked to (as it doesn't address the core issue there). We should tag @Bisaloo comment from here there though as that provides insight into how to resolve it.

[sbfnk]

Test failures are legacy I think - rebasing to (or merging) main should fix these.

[sbfnk]

Looks good to me - have you tested it by running the new action manually on this branch?

[sbfnk]

have you tested it by running the new action manually on this branch?

Just realised that this isn't possible as it won't show up in the list of actions before merging. Second best is probably a test after merge.

[Bisaloo]

Flagging that you may want to integrate these changes since this repo has another workflow pushing files (render-readme): epiverse-trace/packagetemplate#92

[seabbs]

Nice! Looks good to me. Thanks all and particularly @jamesmbaazam.

If anyone fancies doing something similar to epinowcast that would be very much appreciated.

[jamesmbaazam]

I'll do that.