-
Notifications
You must be signed in to change notification settings - Fork 2
/
index.Rmd
184 lines (130 loc) · 10.2 KB
/
index.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
---
title: "SORTÆD: Software Role Taxonomy and Authorship Definition"
image: "cw23.jpg"
links:
- label: GitHub Repository
url: "https://github.com/sdruskat/software-authorship"
output:
postcards::solana # trestles
---
<!--
This website was created as a [hack day activity for the Collaborations Workshop 2023](https://www.software.ac.uk/cw23/hack-day) with the aim to define guidelines for authorship of software.
This activity is necessary because existing authorship guidelines, e.g., for papers, are not easily transferable to software.
The new guidelines will define:
- The importance of authorship specifically for software, taking into account:
- The different authorship roles for software
- Different contribution roles
- The dynamic nature of software development, and different versions of what is perceived to be the “same thing”
- Who is a software author, specifically:
- What criteria are for software authorship
- How these criteria can be applied (giving examples)
- Who is a non-author contributor,
- including example roles of contributors (eg raising bug issues, fixing typos)
- including guidelines for how to identify when an contributor has transitioned to author, and when an author stops being an author
- When and how authors and contributors should be credited
This activity focuses on authorship of software (“the software itself”). It does not discuss specifics of authorship for related outputs (software papers, papers about software, etc.).
-->
Contents:
- [Roles in Software](#roles)
- [Software authorship](#authorship)
- [Guidelines for software projects](#guidelines)
- [How to get involved in SORTÆD?](#get-involved)
{width=90%}
## Software authorship {#authorship}
Developing research software is a dynamic, agile and collaborative effort,
involving a spectrum of contributions. Examples of contributions include project
management, software engineering and reporting bugs. Each of these contributions
has varying impacts on the software.
The objective of Software Authorship is to give a set of definitions, guidelines
and criteria to distinguish authors from non-author contributors of the
software. Because of the dynamic nature of software development and maintenance,
contributors may transition to and from author status as the software evolves.
By defining authors and non-author contributors, appropriate credit and citation
and be given when using the software.
### Who is an author? {#author}
SORTÆD recommends that software authorship be based on substantial contributions to:
1. the conceptualization of the software; OR
2. the source code, documentation and metadata, test code, setup or build configuration of the software; OR
3. maintaining the software or safeguarding the continued existence or sustainability of the software project.<!-- E.g., project manager, governance, community manager -->
In contrast to authorship of textual research outputs:
- software authorship is NOT based on approval of software versions to be released or published;
- software authorship is NOT based on agreeing to be accountable for contributions to the software beyond legal accountability, in ensuring that questions related to the quality and integrity of the software are appropriately investigated and resolved.
All those designated as authors should meet one of the three criteria for authorship,
and all who meet one of the three criteria should be identified as authors.
Those who do not meet one of the four criteria due to the insubstantiality of their contribution
should be acknowledged as contributors (see below).
These authorship criteria are intended to reserve the status of authorship for those who deserve credit.
The responsibility for identifying who meets the authorship criteria lies is part of the governance of the software project, which may choose to recognize authorship beyond the SORTÆD criteria.
If agreement cannot be reached about who qualifies for authorship,
the legal owners of the software should be asked to investigate.
### Non-author contributors {#non-author}
Contributions to software can be made in different roles.
Depending on the type of the contribution, contributors can be eligible for authorship if the contribution is substantial (see above).
Contributors who do not meet the above criteria for authorship should not be listed as authors,
but they should be acknowledged.
The roles that constitute contributorship are detailed in the following.
### Software contributor role taxonomy {#taxonomy}
Supervision
: _Coordinates the project effort, possibly across organizational boundaries_
: Examples: Coordinator, project manager, advisor, team leader
Resources
: _Provision and maintenance of resources used and exposed by the software project, like computational infrastructure and cloud systems_
: Examples: System administrator, cloud manager
Funding
: _Acquisition or management of funding for effort and events that sustain the software_
: Examples: Principal Investigator, work package leader
Outreach
: _Communication with end-users and stakeholders_
: Examples: Training, community manager, user support
Development
: _Writing of the backend and frontend code as well as managing dependencies, making the software ready for release_
: Examples: Programmer, maintainer, UX designer, release manager
Data curation
: _Integration of data in the software and ensures metadata is annotated and available_
: Examples: Data provider, statician, data manager
Testing
: _Unit test, usability, integration tests, release test_
: Examples: Reviewer, reporting user
Documentation
: _Writing of all documentation related to the software, including user guidelines, roadmapping_
: Examples: Technical writer, metadata curator
Conceptualisation
: _Formulation of the idea and goals of the software, design of main features and functionalities_
: Examples: Principal Investigator, Architect, graphical designer, release manager, requirement gathering
### Roles in software {#roles}
{width=90%}
## Guidelines for software projects {#guidelines}
<!--
This section provides guidance for software projects looking to understand how to acknowledge authorship and contributors to their project
-->
### What do you need to do as a project? {#need}
As a research software project, it's useful to be clear and transparent who the authors of your software are, acknowledge contributors, and describe how decisions around authorship are made.
- Authorship: the list of authors should be clearly stated, and ideally made available in a machine readable form as well (e.g. using CodeMeta). A preferred citation for the software project (e.g. in a CFF file) should be included to make it easy to give credit to the authors.
- Contributors: people who have made useful contributions to a project should be acknowledged in documentation, and ideally in project metadata (e.g. in the DOI metadata or in a CodeMeta file).
- Governance: the way the project decides who is an author and who is a contributor should be transparently and publicly documented.
An appropriate place to put this information is in a contribution section in your README or a separate CONTRIBUTING file. There are good existing guidelines for how to structure a project README and CONTRIBUTING file.
### Frequently Asked Questions {#faq}
1. _What is the difference between a contributor and an author?_ A **contributor** is someone who has made a useful contribution to the project, through one or more of the different [contributor roles](#taxonomy). An **author** is someone who has made a more significant contribution to the project, as defined by the [authorship criteria](#author).
2. _When does a contributor become an author?_ A contributor becomes an author, when the people involved in the project governance have decided they meet the criteria.
3. _When does an author stop being an author?_ Generally, authorship is removed when the persons contributions to the current version of the software project are no longer meeting the criteria for authhorship. This may be because the code they have written is no longer included in the release.
4. _Who should I include as an author?_ This will be different for each project, however we recommend the people involved in the governance of the project use the [authorship criteria](#author) and comes up with a set of questions that can be used to assess the significance of someone's contributions. These may not just be contributions of lines of code, but the many other [roles](#taxonomy) that are important in the development of research software.
### Examples of use {#examples}
To be added.
### References {#references}
Some useful references:
- [CReDIT](https://onlinelibrary.wiley.com/doi/epdf/10.1002/leap.1210)
- [AllContributors](https://allcontributors.org/)
- [Contributor Roles Crosswalk](https://zenodo.org/record/4767798)
- [R citation roles](https://journal.r-project.org/articles/RJ-2012-009/)
- [MARC relator codes](https://www.loc.gov/marc/relators/relaterm.html)
- [ROpenSci guidance](https://devguide.ropensci.org/collaboration.html?q=ctb#attributions)
- [SCoRO ontology](https://sparontologies.github.io/scoro/current/scoro.html)
- [Policy on acknowledging the contribution of LLM/AI](https://poldrack.github.io/talks-AIAssistedCoding/talk/talk.html#/title-slide) also [this](https://poldrack.github.io/talks-AIAssistedCoding/talk/talk.html#/section-10) and [this](https://psyarxiv.com/b58ex)
## How to get involved in SORTÆD? {#get-involved}
### How to contribute? {#contribute}
If you would like to contribute to this project, please [open an issue](https://github.com/sdruskat/software-authorship/issues) and get in touch with us.
### How to become an author on this project? {#author}
To become an author on this project, please open an issue with a brief description of what you want to work on and we can discuss it.
### How to cite this project? {#cite}
Use the metadata for this DOI to cite this project:
Leem, Deborah, Turon, Gemma, Gruson, Hugo, Chue Hong, Neil, Kaur Bhogal, Saranjeet, Lo, Sherman, Druskat, Stephan, & Soiland-Reyes, Stian. (2023). SORTÆD: Software Role Taxonomy and Authorship Definition (0.1). Zenodo. [doi:10.5281/zenodo.7896456](https://doi.org/10.5281/zenodo.7896456).