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

[meldra]

Is this the right place?

• This is NOT an addition, alteration or removal of CodeMeta terms. Please raise terms issues in the main CodeMeta repository.
• This is NOT about the CodeMeta Generator. Please raise Generator issues in the Codemeta-Generator repository.

Which pages are affected?

See https://codemeta.github.io/developer-guide/

Which browsers are you seeing the problem on?

Other (describe in next section)

Any other information?

It is a content bug.

[meldra]

@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.

[moranegg]

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.

[meldra]

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?

[meldra]

@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.

[moranegg]

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: ***@***.***>

…