Software Publication

What we believe is good practice

Research software is foundationally important to scientific and social progress, however, traditional acknowledgment of the use of others’ work has not adapted in step with the rapid development and use of software in research. With the research centre signing the Declaration of Research Assessment (DORA), Helmholtz’s Open Science Policy pushing for strategic change and DFG highlighting the role of software in good scientific practice, the tide is turning. The creation and (re)use of research software is first class scholarly output, equivalent to text publications. (Please also note the currently discussed proposal for quality assessment within the HGF: https://arxiv.org/abs/2401.08804)

Creating scientific publications for them is the natural consequence: academic credit can be earned by citations of such software, also bringing often invisible labour of RSEs to light. Instead of hiding software in text publications as appendix or even just mentioning their availability on a social coding platform such as GitHub, they need to be entities of their own, following the FAIR4RS and Software Citation principles.

As always, making software compliant with FAIR does not mean you risk being scooped. Carefully choosing a licence and distribution model for your software should not hold you back from creating metadata publications or use of embargos. Such referenceability for each version of your software is key to enabling larger goals: Reproducibility and Open Science. Software publications usually are updated with any newly released version of a software and provide you with persistent identifiers for both the software as a “concept” as well as for any version.

Can I include software in data publications and the other way around?

• Very often software you write is not meant to be product-like or for longterm reuse at all (application class 1), but very much coupled to the data you process with it. Here, the better choice may be to make it a part of your data publication, intended to result in one, reproducible package. If you plan to reuse your software in multiple projects or discover doing so later on, go ahead and create a separate software publication; you will likely split codebase and data then, too.

• Keep in mind that data and software usually have different licences for good reasons. The REUSE framework helps to keep your licensed materials in check. Also, when mixing analysis code into a data publication, that does not mean you can simply skip all ramifications of legal aspects involved with software!

• Be not afraid to include test data and other necessary materials in your software publication. If test data, etc is reusable for different softwares, potentially go ahead and make it a publication of its own.

Where can I get persistent identification for my software (versions)?

• As soon as your code has matured a little, be sure to start creating versions of it - tags are for free! Forging publications for these versions and using their persistent identifiers as early as possible enables simpler creation of provenance information for your results (see RO-Crates for an example). This is especially true for software matching application classes 2 and 3.

• The usage of general or community archives and repositories like Zenodo, Software Heritage Archive, RADAR, or ASCL creates citable software publications with persistent identifiers. These services mint identifiers of varying granularity. Depending on your needs you should choose carefully - at least a project and its versions should be identifiable, not just projects (see FAIR4RS F1).

• Note that support for software publications in Jülich DATA is under construction at the time of writing (02/2024). Rest assured publications created on Zenodo and other repositories or archives will be reported to the HGF once added to Jülich DATA later in 2024. Research software is not to be registered or published in JuSER, as it lacks proper metadata support, required persistent identifiers for versions and automation capabilities (no API).

• Creating version with tags will allow you to run automated publication pipelines in CI/CD:

• You could use somesy to keep metadata about your project and authors in sync. It will create or update a CITATION.cff or codemeta.json file in your project (see also citation), as well as update Python, JavaScript and Julia packaging metadata files.

• You could use HERMES to create and update publications on Zenodo and other (institutional) repositories. HERMES automatically collates metadata for and enables to create publications without any artifacts or sources (metadata publications). (Support for Jülich DATA under construction)

• When your software is openly available on GitHub, you may look into the GitHub-Zenodo integration.

• Another option is to write a software paper describing the software itself, as a way to make software development count as scientific output in the classical, publication-driven sense. Journals like JOSS, JORS, ACM TOMS, and many others (see https://go.fzj.de/swjournals for a more complete list) allow researchers and code developers to create a publication containing details of the software (version), the implementation, the software engineering aspects, and the area of applications. Some journals offer varying degrees of review and most require payment of an APC, which may be covered by  the central library publication fund (intranet only link). Such a paper, once published, may be mentioned in a README file and/or CITATION.cff file of the repository, asking users to cite this reference publication. Depending on the journal of choice, a version number might be necessary to add to the citation. Note that for provenance and being futureproof, you can mix this kind of publication with the preferred method.

How do I increase findability and visibility for my software?

• Making your software publicly available under an Open Source licence is a great start, because you can use GitHub and other social coding platforms to make it findable. 

• Distributing your software using the ecosystem for packages in your programming language also helps a great deal.

• Having a well written website with your documentation indexed by the major search engines is time well spent.

• Publishing your software helps foster visibility, too. Citations of your software make sure your community can notice, reuse and spread the word by adding more citations.

• Add your published software to catalogues. Using community catalogues like ModelDB (neuroscience), ASCL (Astrophysics), or bio.tools (Bioinformatics) is close to people from your own domain. Cross-domain catalogues are very useful, too, as they reach an even wider audience. Most prominent examples are the Helmholtz Software Directory and the Netherlands eScienceCentre Research Software Directory.

What the FZJ Software Guidelines say about Software Publication

Class 1 and higher
Each software publication of Forschungszentrum Jülich must be documented analogously to data publications in the institutional repository, at least with metadata. Unless a publication is produced, software should be made discoverable in a central internal software catalogue.