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
|
.. sidebar:: ToC
.. contents::
.. _infra-contribute-git-commits:
Writing Commit Messages
=======================
Format
------
On every commit to our revision control system (currently SVN) please provide a commit message of the following form:
::
[CLASS1,CLASS2,...] Short description
Optional long description
* The first line starts with an arbitrary number of tags in square brackets, e.g. ``[CLASS1]`` or ``[CLASS1,CLASS2]``.
See below for a possible list of classes.
* These tags are followed by a short description, try to keep the first line below 120 characters, 80 if possible.
* You can add an optional long description after an empty line.
Possible Classes
----------------
| **NOP**
| Only whitespace changes.
| e.g. removed trailing whitespace, replaced tabs by spaces, changed indentation
| **DOC**
| Changes in the user documentation.
| This includes changes to the DDDoc documentation, README files etc.
| **COMMENT**
| Changes in the source documentation.
| These changes are not visible to the users.
| This includes ``TODO(${name}):`` statements.
| **API**
| Changes in the API.
| These changes classically break backward compatibility.
| e.g. renaming of function names, changing of function parameter order.
| **INTERNAL**
| Changes in the implementation.
| These changes do not influence the public the API.
| e.g. renaming of variable names, simplification of code
| **FEATURE**
| A user-visible feature.
| e.g. extension of an interface, measurable performance improvement
| *If the change is also API breaking the classes FEATURE* **and** *API must be used.*
| **FIX**
| Bug removal.
| If one or more bugs from the ticket tracker are removed then this should be written as ``[FIXED-#7,#35]`` where ``#7`` and ``#35`` are ticket numbers.
| **TEST**
| Addition or changes of tests.
| All code changes that are accompanied with tests must provide the original and the TEST class.
| Don't consider this as a coercion but as a privilege to use both classes!
| **CLI**
| Change to the command line interface of a program.
| e.g. change to the arguments a program accepts, change to the messages printed to the user
| *Output that is meant for debugging or detailed introspection is handled by the LOG class.*
| **LOG**
| Change of output for developers or very advanced users.
| This is the output that is meant for debugging or detailed introspection that is excluded from ``CLI``.
| Such output is usually printed to ``stderr``.
Examples
--------
Example: API Changes
^^^^^^^^^^^^^^^^^^^^
API change with tests and detailed description of changes.
::
[API,TEST] Large changes of align module's API.
This is a large patch that mostly updates the align module:
* The Anchor Gaps specialization is moved from the store module to the align module.
* The Array Gaps class is rewritten.
* Both Anchor and Array gaps have mostly the same API now, differences are documented.
* Greatly unified the interface of the ``globalAlignment()`` and ``localAlignment()`` interface.
* The ``LocalAlignmentFinder`` is now called ``LocalAlignmentEnumerator``.
* Threw out unused DP algorithms (DP algorithm will be cleaned up in the future, see below).
* Clipping of gaps works consistently in both Anchor and Array Gaps data structures.
* Wrote a large number of tests for all changes.
* Adjusted SeqAn library and apps to new API.
All in all, this should make the module more usable, albeit breaking the interface in some cases.
There will be a future change by Rene that strongly unifies the DP algorithms.
This will not inflict another API change, though, and further simplify the align module.
Example: Bug Fixes
^^^^^^^^^^^^^^^^^^
A fix that solves two tickets:
::
[FIX-#240,#356] Fixed iteration of ``ModifiedString``s.
Quite involved fix that allows iteration of ``ModifiedString`` objects.
A fix that does not have a ticket:
::
[FIX] Fixed reading of CIGAR string in module bam_io.
There was a bug when reading the operation "F", which was translated to
FLABBERGASTED. Fixed this to the documented behavior.
Example: Internal Changes
^^^^^^^^^^^^^^^^^^^^^^^^^
An internal change, reordering of code without changing the public API.
::
[INTERNAL] Reordering code in module sequence so no more generated forwards are needed.
An internal change might include tests and improved comments.
::
[INTERNAL,TEST,COMMENTS] Greatly improved transmogrify module.
Restructured the whole internal structure of the module, adding a large number of tests
and improving the source-level documentation. The user level documentation is still
lacking and should be the target of a future change.
Example: Changes To Command Line Interface And Logging
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Changes to the command line interface:
::
[CLI] Changed output of STELLAR such to unify scientific notation floats.
Changes to logging in an app:
::
[LOG] Improved logging in RazerS 5.
Much more detailed logging allows easier debugging. Part of this should probably be
commented out before the next stable release once the dust has settled and most
bugs have been removed.
|
