Making research software open and shareable
Why share research software?
Research software are a fundamental part of research. As with other research outputs, there are good reasons for preserving software and making it available for future use. The benefits of preserving and sharing research software include:
- allowing researchers and developers to get credit for their work
- supporting research integrity by making it easier to reproduce and replicate research results
- promoting open research by creating new opportunities for collaboration and the reuse of software in future research.
- helping researchers and research organisations track the use and reuse of software
Many funding bodies and journal publishers now expect software that supports research findings to be made publicly available upon publication.
How to share research software
Make use of a code repository when developing your software
Make use of a code repository when developing your software
A source code repository is an online service that supports version control and other software development tools such as file hosting, bug tracking and issue tracking. Popular code repositories include GitHub, BitBucket and GitLab. Hosted services are especially useful for working with collaborators across more than one institution.
Imperial College has a license with GitHub that allows users to create both public and private code repositories at no cost. For further information see Working with GitHub.com.
If your project requires extra security beyond that provided by private repositories in GitHub.com you should consider using the College-hosted GitHub Enterprise service. GitHub Enterprise offers similar functionality to GitHub.com, but all code is stored on-premise and a College user account is required to access the service. See Working with GitHub Enterprise for more information.
Document and describe your software
Software documentation provides essential contextual information which describes the software and tells others how the software was created, how it operates and how it can be used. Software documentation can be embedded in the source code or included in written texts that accompany the software. As a minimum you should include a README file with your software.
A README file typically includes information such as:
- the project name
- a description of the project
- instructions on how to install and operate the software
- copyright and licensing information
- where users can find help
GitHub will automatically display the content of a file named README on your repository's top-level page. Consider using Markdown syntax for your README file since GitHub will format this in a manner that makes it more readable and accessible.
Please see this example of a README file and other supporting documentation for a software project in GitHub
Every GitHub repository includes a wiki which can also be used to add descriptive information about your software. For help with creating a README file and a wiki for software projects in GitHub see Documenting your projects on GitHub.
Archive key versions/releases to get a DOI
Code hosting services such as GitHub, BitBucket or GitLab are not suitable for archiving software. If you have software that supports published findings, is needed to reproduce or replicate research results, or has potential for use in future research, we recommend archiving a copy with a data repository such as Zenodo or Figshare. As well as ensuring long-term preservation and access to the software, Zenodo and Figshare both assign DOI’s (Digital Object Identifiers) to software outputs making it easier to cite and track specific versions of your software.
Both Zenodo and Figshare have implemented integration tools to support the automated deposit of software from GitHub. For further information see Making your code citable (for archiving GitHub repositories with Zenodo) and How to connect Figshare with your GitHub account
Choose a licence for your software
What is an open source licence?
A software licence is an agreement between a developer and user which provides a set of conditions for the use and distribution of software. An open source licence allows users to use, copy, modify and redistribute the software providing that credit is given to the author. Because open source licences place minimal restrictions on how others can use software outputs, they are an important tool for making software accessible and reusable.
Which licence should I choose?
When you deposit your software in a repository - whether a code hosting service like GitHub or a general purpose repository like Zenodo or Figshare - you will typically be given the option of choosing a licence. Some popular examples of open source licences for software are Apache 2.0, GNU General Public License (GPL) and MIT. The College’s preferred open source license is the BSD open source licence. Further details are available on the College’s Enterprise Division’s web site: Open Source Software Licences.
A comprehensive list of open source licences with detailed information for each licence is available from the Open Source Initiative’s web page: Licenses and Standards.
If you are planning to modify and/or redistribute someone else's code check to make sure that this is compatible with the permissions granted under the original licence.
What if my software contains IP which can be commercialised?
Open source licences are unlikely to be appropriate for software that are subject to contractual restrictions set by third parties or where the intellectual property rights (IP) for the software are owned by the College and have potential for commercialisation. The College's Intellectual Property policy is available with your College login. Help with the IP commercialisation process is available from the College's Enterprise division: firstname.lastname@example.org
Cite your software
Research software should be given the same importance as any other research output and considered citable in the same way as an article or monograph.
How to enable others to cite your software
If you are making your software publicly available - e.g. via a hosting service such as GitHub or a data repository such as Zenodo or Figshare - you can encourage others to cite your software by including a recommended citation in your README file or by including a CITATION file. If the software supports published findings you should also include a recommended citation in the published paper. This can be added to the acknowledgements section or as part of a separate data access statement.
How to cite others’ software
If you have used someone else's software in your research project you should include a citation in your published paper. This could be in the acknowledgements, footnotes, methods section or appendices depending on publisher requirements. It is not necessary to acknowledge all the software used. The Software Sustainability Institute recommend citation only if the software played a critical role in your research and made a novel contribution.
What to include in a software citation?
The Australian National Data Service (ANDS) recommend using these core citation elements:
Author, Publication Year, Title, Version, Publisher, Resource type (Software), Identifier (e.g. DOI)
Xu, C., & Christoffersen, B. (2017). The Functionally-Assembled Terrestrial Ecosystem Simulator Version 1. Los Alamos National Laboratory (LANL), Los Alamos, NM (United States). [Software]. https://doi.org/10.11578/dc.20171025.1962
Some publishers and software providers have also published guidelines for software citation. Examples can be found on the Software Sustainability Institute’s webpage How to cite software
Australian National Data Service (ANDS) Working with data: Citation and Identifiers
Force 11 Software Citation Principles
Publish a software paper
In addition to making your software publicly available you might also consider publishing a paper describing your software. Journals which specialise in publishing peer reviewed software papers include:
For a more detailed list of journals which accept software papers, see the Software Sustainability Institute's web guide In which journals should I publish my software?
Tell us about your software
The College would like to know about your software and where it is. Once you have archived your software, create a record for it in Symplectic. This will increase its visibility and discoverability. This guide provides instructions on how to deposit information about your software with Symplectic. We have also created this how-to video.
Research software at Imperial
- Research Computing: Using Git to Code, Collaborate and Share (Graduate School workshop)