[Bug]: /developer-guide/ still has a [TBD] #125

Activity

1. meldra

   added

   bug

   content

   on Jun 17, 2026
2. meldra commented on Sep 1, 2026

   

   meldra

   on Sep 1, 2026

   ContributorAuthor

   More actions

   @lindangulopez @moranegg can you please give some guidance on what the current process for this is? It is unclear to me after some poking around if this means basically converting information to or from citation.cff.

   Once I have some guidance, I can write it into the documentation.
3. moranegg commented on Sep 2, 2026

   

   moranegg

   on Sep 2, 2026

   Member

   More actions

   True, there is still a TBD on the page.
   I don't have the exact answer, but I have a reference that can help decide on the best play here.

   1. How do we do citations in SWH from a CodeMeta: https://docs.softwareheritage.org/devel/architecture/citation.html
   2. A blog post about software citation and the SWH feature using CodeMeta: https://www.softwareheritage.org/2025/05/07/software-heritage-citation-feature/

   The section is called: Generating Citations from a CodeMeta document
   (minus the s at the end)

   In general, citing software from a codemeta.json requires translating the metadata in codemeta.json to a citation BibTeX format: https://www.ctan.org/tex-archive/macros/latex/contrib/biblatex-contrib/biblatex-software (like here: https://gitlab.softwareheritage.org/swh/devel/swh-indexer/-/blob/master/swh/indexer/citation/bibtex.py?ref_type=heads)

   So no specific direction.

   👍React with 👍1Reacted by Melissa Draper (el)
4. meldra commented on Sep 3, 2026

   

   meldra

   on Sep 3, 2026

   ContributorAuthor

   More actions

   Thanks @moranegg. Some additional questions:

   1. Are SWHIDs the only software citation ID used like this?

      If I'm understanding this correctly, the output of the reference implementation in the indexer extends beyond just converting CodeMeta to BibTeX; it fuses a CodeMeta conversion result with a SWHID. By which I mean that swhid isn't a thing in the BibTeX @softwareversion crosswalk but exists in the BibLaTeX extension module recommended and which SWH uses.

      I can describe using the crosswalk to make a citation without a SWHID, which would theoretically be the canonical way. I can then follow that up with a description of the fusion scenario above. If there are other implementations they should also be documented, but I'm not aware of any right now.

   2. Would you agree that the documentation for citation generation needs to be split between the dev (the explanation above) and user (how to get a citation generated) guides?
5. meldra commented on Sep 4, 2026

   

   meldra

   on Sep 4, 2026

   Last edited by meldra

   ContributorAuthor

   More actions

   @moranegg (pinging again, sorry) I guess what I'm looking for here, is how much to mention SWHIDs or the SWH Archive, if at all, for the purposes of keeping this site neutral regarding tool recommendations.

   If I'm not mistaken, "How to make codemeta into a citation" basically does not exist on the website unless the user realizes the BibTeX crosswalk exists (and that's not easy to find out about, at least until #130 lands). This PR will thus be dependent though not blocked on #130.

   The main problem I'm seeing with not mentioning SWHIDs/Archive is that this site does a lot of promising that citations and reproducibility are enabled using CodeMeta, but the crosswalk alone is very limited for that; as far as I can tell anyway. Does a codemeta.json typically get updated with the latest commit hash for softwareVersion? I don't think I've seen it happen but I don't know if that's just my limited exposure.

   If not, then just documenting generating a citation only using the conversion with crosswalk seems like it's not fully answering the question this section tries to address, consistent with the promises, even though the answer exists.
6. moranegg commented on Sep 4, 2026

   

   moranegg

   on Sep 4, 2026 via email

   Member

   More actions

   The guideline is NOT to include a SWHID in a codemeta.json file because this will create a race condition. Maybe bolognese tool convert codemeta.json files into BibTeX. I'm not sure. In any case, the archive's feature is an incentive for researchers to add codemeta.json. It will be the same with OSPO-RADAR. Hope it helps. Message ID: ***@***.***>

   …
7. moranegg

   closed this as completedin 31f90f3on Sep 12, 2026
8. bact

   added 2 commits that reference this issue on Sep 14, 2026

   Document citation generation in the developer guide (fix codemeta#125)

   This issue will close once commit 31f90f3 is merged into the 'master' branch.

   31f90f3

   Merge pull request codemeta#134 from meldra/devguide-citations

   ...

   This issue will close once commit 19b326c is merged into the 'master' branch.

   19b326c