In this section

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.

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 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 Imperial-hosted GitHub Enterprise service. GitHub Enterprise offers similar functionality to GitHub.com, but all code is stored on-premise and an Imperial 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

For additional support from the Software Sustainability Institute see Choosing a repository for your software project and Software deposit: Where to deposit software

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. Imperial’s preferred open source license is the BSD open source licence. Further details are available on Imperial’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 Imperial and have potential for commercialisation. Imperial's Intellectual Property policy is available with your Imperial login. Help with the IP commercialisation process is available from Imperial's Enterprise division: enterprise@imperial.ac.uk

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)

Example:

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

Tell us about your software

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

Additional resources

Research software at Imperial

Web pages:

Working with Data and Software at Imperial College
(ICT)
Management of Research Data and Code (Research Support)

Training:

Using Git to Code, Collaborate and Share (Graduate School workshop)

The Software Sustainability Institute

The Software Sustainability Institute website provides comprehensive guidance and links to resources. See in particular their Guides for Researchers and Guides for Developers.