You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pages/rs_quality/fair_rs.md
+68-33Lines changed: 68 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
title: FAIR Research Software
2
+
title: FAIR Research Software Principles
3
3
---
4
4
5
5
@@ -24,29 +24,29 @@ closer to the gold standard of fully reproducible research.
24
24
25
25
### Findable
26
26
- Create a description of your software to make it discoverable by search engines and other search tools
27
+
- Use standards (such as [CodeMeta][codemeta]) to describe interoperable metadata for your software (see [Research Software Metadata Guidelines][rsmg-1])
27
28
- Place your software in a public software repository (and ideally register it in a [general-purpose or domain-specific software registry][software-registries])
28
29
- Use a unique and persistent identifier (DOI) for your software (e.g. by depositing your code on [Zenodo][zenodo]),
29
30
which is also useful for citations - note that depositing your data/code on GitHub and similar software repositories
30
31
may not be enough as they may change their open access model or disappear completely in the future, so archiving your code means it stands a better chance at being preserved
31
32
32
33
### Accessible
33
-
- Make sure people can freely, legally and easily get a copy your software
34
-
- Structure your code using common patterns and use coding conventions to make your code readable and understandable by people (once they obtain a copy of it), i.e. make your code accessible in the *intelligible* sense
35
-
- The code and its description has to be available even when the software is no longer actively developed (this include previous versions of the software)
34
+
- Make sure people can obtain get a copy your software using standard communication protocols (e.g. HTTP, FTP, etc.)
35
+
- The code and its description (metadata) has to be available even when the software is no longer actively developed (this includes earlier versions of the software)
36
36
37
37
### Interoperable
38
38
- Explain the functionality of your software and protocols for interaction with it
39
-
- Use standard formats for inputs and outputs
39
+
- Use community-agreed standard formats for inputs and outputs of your software and its metadata (e.g. [CodeMeta][codemeta])
40
40
- Communicate with other software and tools via standard protocols and APIs
41
41
42
42
### Reusable
43
-
- Document your software (including its functionality, and how to install and run it) to make it more understandable by others who may wish to reuse or extend it
44
-
- Follow best practices for software development (including structuring your code in reusable functions with a single functionality
45
-
that can be built on top of, coding conventions, code readability and verifying its correctness)
46
-
- Test your software and make sure it works on different platforms/operating systems to make it more reusable
43
+
- Document your software (including its functionality, how to install and run it) to make it more understandable by
44
+
others who may wish to reuse or extend it
45
+
- Follow best practices for software development, e.g. structure your code using common patterns and use coding
46
+
conventions to make your code readable and understandable by people
47
+
- Test your software and make sure it works on different platforms/operating systems
47
48
- Give a licence to your software clearly stating how it can be reused
48
49
- State how to cite your software, so people can give you credit when they reuse it
49
-
- Include a contributor policy so that others can contribute to your code and credit for contributions is provided
50
50
51
51
## Tools and practices for FAIR research software development
52
52
@@ -61,15 +61,15 @@ software may be FAIR, but still not very good in terms of its functionality.
61
61
62
62
### Development environments
63
63
64
-
Virtual and integrated development environments (IDEs), such as VS Code or PyCharm, help with running, testing, and debugging code.
65
-
Virtual environments further enable us to share our working environments with others, making it easier to access, reuse and extend our code.
64
+
Virtual and integrated development environments (IDEs), such as VS Code or PyCharm, help with reading, running, testing, and debugging code.
65
+
Virtual environments further enable us to share our working environments with others, making it easier to reuse and extend our code.
66
66
IDEs often provide integrations with other tools, e.g. version control and command line terminals, enabling you to do many tasks from a single environment,
67
67
saving time in switching between different tools.
68
68
69
69
### Command line terminals
70
70
71
71
Command line terminals (e.g. Bash, GitBash) enable us to run and test our code without graphical user interfaces (GUI) afforded to us by IDEs -
72
-
this is sometimes needed for accessing and running our code remotely on servers and high-performance systems without a GUI provision, where time,
72
+
this is sometimes needed for running our code remotely on servers and high-performance systems without a GUI provision, where time,
73
73
memory and processing power are expensive or in high demand.
74
74
75
75
Version control systems are typically provided as command line tools, making them often only accessible from command line terminals to enter commands and access
@@ -106,7 +106,31 @@ correctly on their machine - helping with code understanding and reusability.
106
106
Following coding conventions and guides for your programming language that is agreed upon by the community and other programmers
107
107
are important practices to ensure that others find it easy to read your code, reuse or extend it in their own examples and applications.
108
108
109
-
### Software- and project- level documentation
109
+
110
+
### Code licensing
111
+
112
+
A licence is a legal document which sets down the terms under which the creator of work (such as written text,
113
+
photographs, films, music, software code) is releasing what they have created for others to use, modify, extend or exploit.
114
+
115
+
It is important to state the terms under which software can be reused - the lack of a licence for your software
116
+
implies that no one can reuse the software at all.
117
+
A common way to declare your copyright of a piece of software and the license you are distributing it under is to
118
+
include a file called LICENSE in the root directory of your code repository.
119
+
120
+
Some good resources to check out for choosing a licence for your code:
121
+
122
+
-[The open source guide][opensource-licence-guide] on applying, changing and editing licenses.
123
+
-[choosealicense.com][choosealicense] has some great resources to help you choose a license that is appropriate for your needs,
124
+
and can even automate adding the LICENSE file to your GitHub code repository.
125
+
126
+
### Code citation
127
+
128
+
We should add a citation file to our repository to provide instructions on how and when to cite our code.
129
+
A citation file can be a plain text (CITATION.txt) or a Markdown file (CITATION.md), but there are certain benefits
130
+
to using use a special file format called the [Citation File Format (CFF)][cff], which provides a way to include richer
131
+
metadata about code (or datasets) we want to cite, making it easy for both humans and machines to use this information.
132
+
133
+
### Code- and project- level documentation
110
134
111
135
Documentation comes in many forms - from **software-level documentation** including descriptive names of variables and functions and
112
136
additional comments that explain lines of your code, to **project-level documentation** (including README, LICENCE, CITATION, CONTRIBUTING, etc. files)
@@ -124,46 +148,48 @@ You should check the rules or guidelines of your institution, grant or domain on
124
148
125
149
Some examples of commonly used software repositories and registries include:
126
150
127
-
- general-purporse software repositories - [GitHub][github] and [GitLab][gitlab]
151
+
- general-purpose software repositories - [GitHub][github] and [GitLab][gitlab]
- software registries - [BioTools][biotools] (for biosciences) and [Awesome Research Software Registries][awesome-rs-registries], providing a list of research software registries (by country, organisation, domain and programming language) where research software can be registered to help promote its discovery
153
+
- software registries - [BioTools][biotools] (for biosciences) and [Awesome Research Software Registries][awesome-rs-registries], providing a list of research software registries (by country, organisation, domain and programming language) where research software can be registered to help promote its discovery
130
154
131
155
### Persistent identifiers
132
156
133
-
Unique persistent identifiers, such as Digital Object Identifiers (DOIs) provided by Zenodo, FigShare and similar digital archiving services, and commits/tags/releases used by GitHub and similar code sharing platforms,
157
+
Unique persistent identifiers, such as **Digital Object Identifiers** (DOIs) provided by [Zenodo][zenodo],
158
+
[FigShare][figshare], etc., or **SoftWare Heritage persistent IDentifiers** ([SWHID](swhid)) provided by [Software Heritage][software-heritage],
159
+
and similar digital archiving services, and commits/tags/releases used by GitHub and similar code sharing platforms,
134
160
help with findability and accessibility of your software, and can help you get credit for your work by providing citable references.
135
161
136
162
### Tools for assessing FAIRness of software
137
163
138
-
Here are some tools that can check your software and provide an assessment or measurement of its FAIRness:
164
+
Here are some tools that can check your software and provide an assessment of its FAIRness:
139
165
140
166
-[FAIRsoft evaluator][fair-rs-evaluator]
141
167
-[FAIR software test][fair-rs-test]
168
+
-[`How FAIR is your software` - command line tool to evaluate a software repository's compliance with the FAIR principles][howfairis]
169
+
170
+
### Summary
142
171
143
172
The table below provides a summary of how different tools and practices help with the FAIR software principles.
0 commit comments