Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Preserving your software in the scholarly record

The first step to making your code discoverable is to put it online. However, not all websites are equally reliable or future-proof. A UC OSPO study found that 30% of experienced UC open source contributors have, at one time or another, shared their code on a custom website, such as a lab website (Scarlett et al. 2026). These custom websites may be useful for temporary or informal communications, but they should not be considered the “version of record”. Complement (or replace) these communications with persistent identifiers pointing to scholarly repositories or well-established version control platforms, and other researchers will have an easier time finding your code and giving you credit for it.

In this section, we’ll discuss software citation, authorship agreements, software papers, succession planning, and archival. Many of these practices are easily overlooked in the hectic research process, and they are also easily confused, since guidance changes quickly. Luckily, the UC Libraries and the UC OSPO Network provide robust support for them.

Software citation and authorship agreements

In academia, researchers tend to find useful new tools through papers and citations. For better or for worse, citations are also a key metric for measuring the success of an academic researcher’s career during hirings and performance reviews. Whether or not you are personally concerned about your citation count, you should consider citability part of your sustainability strategy. Citations help others find your work, they help your work persist in the academic record, and they help other researchers and the public understand where your contributions fit into the larger academic context.

Software citation refers to citation of actual software programs, not just papers that describe software. Historically, this practice was not common, but as software has become an increasingly accessible and indispensable component of research infrastructure, it has become clear that norms and tools for citation of software itself are badly needed. The more people cite software, the less pressure there will be for developers to write descriptive software papers simply for the purpose of having a citable artifact. Citing software can be challenging if the software’s authorship, versioning, or other metadata are unclear. By implementing the checklist below, you can make the task of citation easier for your readers and users.

For developers

Here’s an example of a complete software citation. Whether you want users to use a DOI, a SWHID, or a commit hash is up to you, but you should give instructions in your README that make it easy for your users to generate a citation like this one.

An illustration of a proper software citation, with arrows pointing to the fact that it names the authors, provides a DOI, and provides version numbers, using SemVer semantic versioning or a git hash. The citation reads as follows: Bear, Oski and Bruin, Josephine. (2026). UCCool [software] version 1.2.3. Zenodo. https://doi.org/10.1234/zenodo.1234567.

For authors

If you’re an academic software creator, you’re probably at times an author, citing software that you have used. You should properly cite others’ software, too!

The first place to look for citation metadata is the code repository, and specifically check whether it has a CITATION.cff file. If it does, you should use it. Some citation management tools, such as Zotero, have native cff support, so you can directly import the cff file into your citation manager. For other citation managers, you will have to convert the cff file to a different format using a tool such as cffconvert.

The next best place to look for citation information is the project’s README and/or other documentation. Do not use the GitHub “cite this repository” citation as-is, as this citation is not up to the latest scholarly standards. Package registries such as PyPI and CRAN are a last resort, since these are often incomplete and/or out of date.

A stylized illustration of a person with a magnifying glass, searching through a page that says "Where to find citation info: 1. CITATION.cff. 2. README. 3. Package registry".

If the creators do not provide a recommended software citation, or the one they provide is incomplete, you should craft one yourself, addressing the four W’s (Chue Hong et al. 2019): Who, When, What, and Where–these are described below. Here is a checklist for authors citing software, again paraphrasing the FORCE11 Software Citation Implementation Working Group’s advice (see also Katz et al. 2021):

Authorship agreements

One of the most common challenges in citing software is figuring out who wrote it. As a developer or creator of academic software, it’s your responsibility to make clear who are the authors of the software, who are contributors, and the implications of each. We recommend having a formal conversation with your team about authorship criteria, using some standard set of roles or criteria such as the CRediT taxonomy, the ICMJE authorship guidelines, or the COPE guidelines on authorship disputes. Even if you aren’t publishing a paper, your README should recommend a software citation with clear authors.

In addition to promoting consistent citation practices, recognition of contributions improves inclusivity and morale. If you publish a paper, consider putting contributors who don’t meet the authorship criteria in your acknowledgements section. The All Contributors project also makes it easy to showcase who contributed to your repo and in what ways. The All Contributors specification has been implemented on GitHub, in an R package, and as a command-line tool. Finally, if you use a chat space with channels such as Discord or Zulip, consider creating a #gratitude or #praise channel where you can express your thanks to volunteers, and/or where they can thank you.

A screenshot showing a website with cards that each lists a contributor's name, shows their portrait, and lists their roles, such as "Tyler Benning - Maintenance; Code; Design".

Example of a website that showcases their contributors using the All Contributors app (source: https://allcontributors.org/).

Some mature open-source projects use a Contributor Licensing Agreement (CLA) to clarify, among other things, copyright ownership of community contributions. However, this is very unusual in academic projects, and writing a CLA is not straightforward. We recommend that you do not try to implement a CLA yourself, but rather come talk to us here at the UC OSPO Network if you’re interested in a CLA.

Should I publish a software/hardware paper?

Papers are the traditional currency of academic merit. While many departments are moving beyond this narrow view of research success, many researchers, especially junior researchers, still feel the pressure to publish papers that will garner citations. A software paper serves as a helpful guide to beginners, and yields citations that are easily tracked. On the other hand, it is time-consuming to produce, and can’t be modified as your software develops. Therefore, whether to write a software paper depends on your bandwidth and your goals.

Papers solely about a piece of software are often called software papers (there are also hardware papers and data papers). These papers are usually much shorter than a typical research paper, sometimes just one or two pages. The length and format will depend on whether you are submitting to a traditional journal that also accepts software papers, such as PLOS One or PeerJ, the software track of a traditional journal, such as Bioinformatics’ Application Notes, or a journal that specializes in software papers, such as the Journal of Open Source Software (JOSS), the Journal of Open Research Software (JORS), or SoftwareX. The Software Sustainability Institute maintains a list of journals that accept software papers here. Some open-source hardware journals include Hardware, HardwareX, and the Journal of Open Hardware.

If you decide to publish a paper about your software, consider publishing open access. The UC has negotiated agreements with various publishers that grant UC researchers discounts or even waive the article processing charges (APCs) altogether. A full list of these agreements is maintained here. You can also search for any agreements with a particular journal in the California Digital Library’s JOLT tool. The Journal of Open Source Software (JOSS) is a popular open-access software journal that does not charge any APCs. Their workflow is entirely public and GitHub-based, and review is usually fairly quick. However, JOSS papers are not indexed in Web of Science or Scopus, so users of these commercial tools will not see them.

If you simply want a DOI and do not wish to bother with peer review, consider publishing on a preprint server such as arXiv or SocArXiv, or depositing your software paper in eScholarship, UC’s open access institutional repository. As with preprints, most journals will allow you to publish an article that you’ve already deposited in eScholarship.

Succession planning and archival

All projects have a beginning and an end. Sometimes the end comes very suddenly, and other times it is a gradual wind-down. Either way, it’s easy to forget the importance of deliberately sunsetting a project. It can be uncomfortable to talk about how an active project might end, or it might just be inconvenient to sit down and plan for the future. However, it’s important to talk with your team about such questions as:

ANECDOTE FROM INTERVIEW HERE

do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."

Succession planning means planning for continuity in project operations even as individual leaders come and go. In academic open source, succession planning is often a matter of ensuring that core project operations don’t depend on just one person. ::: {tip} Succession planning checklist

Archival refers to preservation of your software as a scholarly artifact. As discussed above, this helps ensure that your work is findable to others who may want to build on it, even after you have moved on to other things. If you’ve already made your code citable with a DOI, you’ve done most of the work of archival. Here are a few more things you should do.

Many of the UC OSPO Network’s staff and volunteers are affiliated with UC libraries. If you have any questions about citation or archival, please reach out to us or attend our office hours.

Want to learn more about scholarly preservation of software? Check out these related resources.

Software Citation

Authorship & Contributor Agreements

Software Papers

Succession Planning

Archival & Repositories

References
  1. Scarlett, V. T., Curty, R. G., Gomez, J., Langdon, L., Janée, G., & Budden, A. E. (2026). A system-wide snapshot: A multi-campus survey of open source contributors at the University of California. PLOS One, 21(6), e0348894. 10.1371/journal.pone.0348894
  2. Katz, D. S., Bouquin, D., Hong, N. P. C., Hausman, J., Jones, C., Chivvis, D., Clark, T., Crosas, M., Druskat, S., Fenner, M., Gillespie, T., Gonzalez-Beltran, A., Gruenpeter, M., Habermann, T., Haines, R., Harrison, M., Henneken, E., Hwang, L., Jones, M. B., … Zhang, Q. (2019). Software Citation Implementation Challenges. arXiv. 10.48550/ARXIV.1905.08674
  3. Chue Hong, N. P., Allen, A., Gonzalez-Beltran, A., de Waard, A., Smith, A. M., Robinson, C., Jones, C., Bouquin, D., Katz, D. S., Kennedy, D., Ryder, G., Hausman, J., Hwang, L., Jones, M. B., Harrison, M., Crosas, M., Wu, M., Löwe, P., Haines, R., … Pollard, T. (2019). Software Citation Checklist for Authors. 10.5281/ZENODO.3479198
  4. Chue Hong, N. P., Allen, A., , Gonzalez-Beltran, de Waard, A., Smith, A. M., Robinson, C., Jones, C., Bouquin, D., Katz, D. S., Kennedy, D., Ryder, G., Hausman, J., Hwang, L., Jones, M. B., Harrison, M., Crosas, M., Wu, M., Löwe, P., Haines, R., … Pollard, T. (2019). Software Citation Checklist for Developers. 10.5281/ZENODO.3482768
Facet 1 - Discoverability
✅ What is discoverability?
Facet 1 - Discoverability
Documentation