Publishing research software openly: Advice and best practices

Select a repository, which can assign persistent identifiers, such as DOIs, to your software when you publish, to ensure that your code can be cited and linked to in a sustainable way. Ideally, publish related code, data, and documentation together in the same repository. Should these be published separately, ensure they reference each other using persistent links.

• If you have a specific version of code and data associated with a project or article, consider publishing your files in a research data repository. At the Swedish National Data Service (SND), publications are assigned persistent identifiers, and your publication will be preserved and archived at SLU.
• Software, which you plan to maintain and develop further, can be published in a code repository such as GitLab or GitHub. GitHub offers the possibility of assigning a DOI to a specific version of the code through an integration with Zenodo.
• Software packages can also be published in a package repository, such as CRAN, PyPI, or Bioconductor.
• To increase discoverability, you can register your published software in a community registry, such as rOpenSci.
• You can also increase visibility of your published software by describing it in a scientific article. Some journals specialise in software descriptions (e.g., The Journal of Open Source Software), while discipline-specific journals may offer dedicated article types (e.g., "software notes" or "software articles"). Writing an article provides the opportunity to describe your software in greater detail, and you can encourage users of your software to cite the article.

Learn more

• Swedish National Data Service (SND)
• GitHub, a platform, where developers can create, store, manage, and share code
• CRAN (The Comprehensive R Archive Network), a network for archiving and distributing software for the R programming language
• The Python Package Index (PyPI), a repository for software written in Python
• Bioconductor, a project dedicated to developing, supporting, and disseminating free and open-source software for bioinformatics
• rOpenSci,  a non-profit initiative working towards open and reproducible research using shared data and reusable software

• Organise files according to a logical folder structure that separates underlying data, code, and results.
• Use descriptive names for files and folders to make it clear which file does what.
• Version software and associated data separately. You can distinguish file versions by the file names or by using version control tools like Git.

• Divide your code into modules or packages with clear purposes and boundaries.
• Indent code blocks using tabs or spaces, following the conventions of the programming language you are using.
• Use descriptive names for functions, classes, and variables to make it easier to understand what they contain.
• Tidy your code before publication. For instance, remove code blocks you have disabled with comment characters if they no longer serve a purpose in the program.

Make it easier for others to understand how the software is used and what the code does, by documenting it thoroughly.

• Include a README file, which is a plain text file directly readable by a user.
  • In the README file, describe how the software is run and used. Include any information that is useful for a user to know, for example if there are help commands available. If relevant, describe how the program is compiled.
  • Should the published code include multiple source code files, detail what each file does. Document whether the files are intended to be run as scripts, and, if so, if they are to be run in a specific order.
  • Include references to any other scientific publications, which the code or analysis methods are based on.
• Add comments in the code to describe what the code does and why.
• Begin each source code file with a header in the form of a comment that includes:
  • Title
  • A description of what the file does and how it relates to other files in the publication
  • Version
  • Date
  • Identifier for the code publication (e.g., DOI)
  • Identifiers or references to related publications (e.g., an article, report, or data publication)
  • Contact details of the creator (name, email, and if relevant ORCID and affiliation)
  • Licence information, if applicable
• One way to document workflows is to employ so-called "literate programming". Here, programming code is interspersed with text written in natural language. This can be done by using the Markdown markup language. Using Markdown allows you to create reproducible reports containing text and analysis results, which can be converted into PDF or Word documents. Quarto is a popular system for combining code with Markdown, which can be used for literate programming.
• Another way of documenting workflows is to use a script that automates the steps in the process.

Learn more

• Information on author identifiers, including ORCID, from the SLU Library
• How to specify affiliation with SLU when publishing
• Quarto, an open-source scientific and technical publishing system 

To ensure that the software can be used over time, it is important to describe the environment within which the program was created. Specify the version of the operating system, programming language, and any libraries, modules, or packages used by the program. This can be done in different ways:

• Include this information in the README file. 
• In R, you can use the command “sessionInfo()”  to retrieve the current information after running your program. You can save the output as a text file and publish it together with the code. 
• Another way is to include the information in the form of a metadata file, which can be read by supporting software, for example Pipenv for Python or renv for R. 
• To facilitate the recreation of the environment needed to run the software, you can make use of the so-called container technology. Thus, a tool, such as Docker, packages the code together with associated software libraries in order for it to be run in isolation in a controlled environment and, hence, work on different computers. 

Learn more

• Docker, a platform for creating containers

Open source means that software is free to use, modify, and share. If possible, avoid making your published code dependent on non-open source software. Prior to publishing, it is important to ensure that you hold the rights to the software in its entirety and thereby have the right to distribute it.

• Software that you have created yourself can be provided with a license specifying how it may be reused. Licences that meet open source requirements are preferable.
• Include the licence information as a text file named LICENSE.txt (or LICENSE.md if using Markdown). Moreover, add a copyright statement in the header of the source code file. Alternatively, you can paste the full licence text into the source code file itself.
• All persons involved in the creation of the software must consent to its publication.
• When reusing parts of code created by someone other than yourself, you must comply with the licence provided. If the code has not been provided with a license permitting re-publication, you will need permission from the copyright holder before publishing your software.
• Remember to cite when using code created by someone else.

Learn More

• The Choose a Licence website provides guidance on selecting a software licence.
• Read more about citing and referencing code in the SLU library’s guide to referencing.

Ensure that the software runs successfully before publishing your code. It is recommended to test whether the program works as expected on a computer other than your own. If possible, ask a colleague to review and test run your code on their computer.

• Make sure that all the files needed to run the program are included in the publication.
• Check that the file paths point to files within the published folder structure, and not to locations specific to your own computer. This is referred to as using relative paths instead of absolute paths.
  • Example of an absolute path in Windows: "C:\Users\jdoe\research_project\analysis\article2024\mycode\data\data_file.csv"
  • Example of a relative path in Windows: "..\data\data_file.csv"
• Some journals require that you make data and code available already during the peer review process of an article. Should you choose to publish via the Swedish National Data Service (SND), you can share your files with the reviewers, without publishing them openly until the article has been accepted.

Learn more

• If you have been asked by a colleague or journal to review someone else’s code, you may find advice here: Implementing code review in the scientific workflow: Insights from ecology and evolutionary biology.