Skip to content

Commit 7acc64c

Browse files
dweindlFFroehlichsvenjakemmer
authored
Doc: Add description of PEtab development process (#507)
* Doc: Add description of PEtab development process As drafted and agreed on by the PEtab authors. * Apply suggestions from code review Co-authored-by: Fabian Fröhlich <[email protected]> Co-authored-by: Svenja Kemmer <[email protected]>
1 parent 42ab89e commit 7acc64c

File tree

2 files changed

+223
-0
lines changed

2 files changed

+223
-0
lines changed

‎doc/development.rst‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
.. _development:
2+
3+
PEtab development process
4+
=========================
5+
6+
Motivation for this document / general remarks
7+
++++++++++++++++++++++++++++++++++++++++++++++
8+
9+
Reproducibility and reusability of the results of data-based modeling
10+
studies are essential. Yet, until recently, there was no broadly supported
11+
format for the specification of parameter estimation problems in systems
12+
biology. Therefore, we developed PEtab. Having released the specifications
13+
for PEtab version 1.0, we would like to keep development of PEtab active by
14+
attracting more users and tool developers. We acknowledge that it is
15+
important for any potential contributors to know how PEtab is managed and
16+
developed, which we will explain in the remainder of this document.
17+
18+
Values
19+
++++++
20+
21+
We are committed to diversity, open communication, transparent processes,
22+
democratic decision-making by the community and fostering a welcoming
23+
environment. While we want to have clear processes, we don’t want to
24+
overformalize things to avoid unnecessary slowdowns.
25+
26+
Roles within the PEtab community
27+
++++++++++++++++++++++++++++++++
28+
29+
The following subsections describe the different roles in the development of
30+
PEtab.
31+
32+
Anybody interested in PEtab
33+
---------------------------
34+
35+
Input from every interested person is welcome.
36+
37+
Anyone may...
38+
39+
* propose changes to PEtab
40+
41+
PEtab forum
42+
-----------
43+
44+
The PEtab forum includes anybody who is interested in PEtab and is
45+
subscribed to the `PEtab mailing list <https://groups.google.com/g/petab-discuss>`_
46+
using their real name. (Although anybody is invited to subscribe to the
47+
mailing list with any name or email address, we require the use of real
48+
names for participation in any votes. This is to ensure that every person
49+
has only one vote.)
50+
51+
The PEtab forum ...
52+
53+
* votes for changes to PEtab
54+
* nominates editors
55+
* elects editors
56+
57+
PEtab editors
58+
-------------
59+
60+
PEtab is meant to be a community effort. Decisions should therefore be made
61+
as far as possible by a broad community interested in the use and
62+
development of PEtab. Nevertheless, such a project cannot run fully
63+
autonomously, but requires a core team of editors to take care of certain
64+
management tasks. The PEtab editorial board is a team of 5 representatives
65+
nominated and elected by the PEtab forum.
66+
67+
The duties / privileges of the editors include the following:
68+
69+
* organizing polls
70+
* writing/updating specifications
71+
* organizing and announcing annual meetings / hackathons
72+
* promoting PEtab
73+
* deciding minor PEtab issues among themselves
74+
("minor" as defined by the editors but reasons for the decision need to be communicated)
75+
* managing the PEtab mailing lists
76+
* managing the PEtab GitHub organization and respective repositories
77+
* delegating any of the above
78+
79+
Other
80+
-----
81+
82+
Other roles may be created as required based on the decision of the editors by majority vote.
83+
84+
Communication channels
85+
++++++++++++++++++++++
86+
87+
The main discussion channel should be the GitHub
88+
`issues <https://github.com/PEtab-dev/PEtab/issues>`_ /
89+
`discussion <https://github.com/PEtab-dev/PEtab/discussions>`_ pages.
90+
Additionally, the `mailing list <https://groups.google.com/g/petab-discuss>`_
91+
is used for the announcement of new releases, polls, and the likes and can be
92+
used for discussions that seem unfit for GitHub. An archive of the mailing list
93+
shall be publicly accessible.
94+
The PEtab Editors can be contacted through
95+
`https://groups.google.com/g/petab-editors <https://groups.google.com/g/petab-editors>`_,
96+
which is only readable by the current Editors.
97+
Regular, ideally non-virtual, PEtab hackathons are planned to happen at least
98+
annually, e.g., in combination with
99+
`COMBINE events <https://co.mbine.org/events/>`_.
100+
101+
Election of Editors
102+
+++++++++++++++++++
103+
104+
Editors are elected for 3 years by the PEtab forum. Editors may serve
105+
multiple terms, but there needs to be a break of 1 year between subsequent
106+
terms. To maintain continuity, not all editors shall be replaced at the same
107+
time. Editors may resign any time before the end of their term.
108+
109+
Whenever an Editor position becomes vacant:
110+
111+
* Editors announce upcoming elections and request nominations via the PEtab
112+
mailing list. The time given for nominations shall be no shorter than 10 days.
113+
* Interested parties submit nominations including a short statement on the
114+
reason for nomination before the deadline. Self-nominations are allowed.
115+
* Editors ask the nominees whether they accept the nomination (nominees are
116+
given 5 days to accept). This step may start already during the nomination
117+
phase.
118+
* Editors announce the nominees who accepted their nomination along with the
119+
submitted statements and open the poll via the PEtab mailing list. The
120+
editors choose a sensible medium and deadline for the poll.
121+
* The PEtab forum casts their votes secretly. (Votes may have to be open to the
122+
editors, as they need to verify that only qualified votes are counted.
123+
However, the editors are required to maintain confidentiality.) Every
124+
participant has 1 vote per vacant position.
125+
* After passing the deadline, the editors count the votes and ask the
126+
editor-elect to accept or decline the election. No acceptance before the end
127+
of the deadline set by the editors, which shall not be less than 3 days, is
128+
considered decline.
129+
* If an editor-elect declines, the position will be offered to the next
130+
candidate according to the number of votes. (If there is no candidate left
131+
with at least one vote, the election for the vacant position needs to be
132+
repeated.
133+
* If there is a tie between candidates of which only a subset can become an
134+
editor, run-off elections including only those candidates have to be
135+
organized by the PEtab editors as soon as possible. Voters will again have a
136+
number of votes equal to the number of vacant positions.
137+
* If the editor-elect accepts, the other editors announce the new editor on the
138+
PEtab mailing list. The editors shall furthermore announce the number of
139+
votes each nominee, elected or not, has received.
140+
141+
Special procedure for the first election (February, 2021):
142+
----------------------------------------------------------
143+
144+
The first election was held among the authors of the original PEtab
145+
publication. Nominees were not required to be among the authors. The election
146+
was managed by two persons who were not among the candidates and were
147+
coming from two different labs. To avoid a simultaneous replacement of all
148+
of the editors elected during the first election, the first election was
149+
subject to the following special rules: 2 persons were elected for 3
150+
years, 2 persons for 2 years and one person for 1 year. The persons with
151+
more votes were elected for a longer period (if they accepted
152+
for the longer period). In case of an equal number of votes among any of the
153+
top 5 candidates, there would have been run-off elections between those
154+
candidates with equal numbers of votes. The editors-elect were given 3 working
155+
days to accept the election.
156+
If an editor would decide to hand over his editorial role before the end of
157+
their term, an editor elected for a shorter term period could decide to take
158+
over and extend their term to the end of the leaving editor's original term.
159+
160+
PEtab format development process
161+
++++++++++++++++++++++++++++++++
162+
163+
We acknowledge that PEtab cannot accommodate everybody’s needs, but we are
164+
committed to addressing current and future requirements in upcoming versions of
165+
the PEtab format. Although we value backwards-compatibility, we don’t want to
166+
exclude breaking changes if justified by the benefits.
167+
168+
Anybody is welcomed to propose changes or additions to PEtab. Any proposals
169+
shall be made using GitHub issues. Benefits, problems, and potential
170+
alternatives shall be discussed in the respective thread.
171+
172+
A proposal is considered accepted for inclusion in the next version of PEtab
173+
if it’s endorsed by the majority of the PEtab editors and if distinct
174+
developers of at least 2 tools provide a prototype implementation. For any
175+
changes, respective test cases sufficiently covering the changes are to be
176+
added to the `PEtab test suite <https://github.com/PEtab-dev/petab_test_suite>`_
177+
prior to release.
178+
179+
Requirements for new releases:
180+
181+
* Updated format specifications
182+
* Updated converter
183+
* Updated validator
184+
* Updated test suite
185+
* Updated changelog
186+
187+
The PEtab editors jointly decide whether these requirements are met.
188+
189+
Upon a new release, the PEtab editors ensure that
190+
191+
* a new release is created in the GitHub repository
192+
* the new version of the specifications is deposited at Zenodo
193+
* the new release is announced on the PEtab mailing list
194+
195+
Versioning of the PEtab format
196+
------------------------------
197+
198+
The PEtab specifications follow `semantic versioning <https://semver.org/>`_.
199+
Any changes to the PEtab specifications require a new release. Any necessary
200+
clarifications or corrections shall be collected on an Errata page until a new
201+
version is released.
202+
203+
The time for a new PEtab release is left to the discretion of the editors.
204+
However, accepted changes should be released within 2 months after acceptance.
205+
206+
With any new PEtab version it shall be ensured that a converter between the new
207+
and the previous version(s) is available. Parallel maintenance of multiple
208+
versions is not intended.
209+
210+
Generally, any parameter estimation problem that could have been specified
211+
in an earlier version should be specifiable in a new version (potentially
212+
requiring different syntax). Any changes to the PEtab specifications that
213+
would remove certain features without adequate replacement require the
214+
support of at least 4 out of the 5 editors.
215+
216+
Changes to these processes
217+
++++++++++++++++++++++++++
218+
219+
Changes to the processes specified above require a public vote with
220+
agreement of the majority of voters. Any other changes not directly
221+
affecting those processes, such as changes to structure, orthography,
222+
grammar, formatting, the preamble can be made by the editors any time.

‎doc/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
:caption: About
2020

2121
Changelog <CHANGELOG.md>
22+
Development <development>
2223
how_to_cite
2324
license
2425
logo/LICENSE.md

0 commit comments

Comments
 (0)