6 <link href="style.css" type="text/css" rel="StyleSheet" /> |
6 <link href="style.css" type="text/css" rel="StyleSheet" /> |
7 </head> |
7 </head> |
8 <body> |
8 <body> |
9 <h1>Sane Software Manifesto</h1> |
9 <h1>Sane Software Manifesto</h1> |
10 |
10 |
|
11 <p>In respect to user freedoms, privacy, liberty, quality, mental health and world peace we create software according to these guidelines.</p> |
|
12 |
|
13 <h2>Free software</h2> |
11 |
14 |
12 <p>In respect to user freedoms, privacy, liberty, quality, mental health and world peace we create software according to these guidelines.</p> |
15 <ul> |
13 |
16 <li>user has freedoms</li> |
14 |
17 <li>user controls his/her computer and software and owns the data</li> |
15 <h2>free software</h2> |
18 <li>non-free software can not be trusted </li> |
16 |
19 <li>must be buildable using free software toolchain (like GNU/Linux + GCC or OpenJDK etc.)</li> |
17 user has freedoms |
20 <li>should not promote non-free (proprietary) software or services</li> |
18 user controls his/her computer and software |
21 <li>copyleft licenses (like GNU GPL or GNU Affero GPL) are recommended because they guarantee software freedoms to every single end-user and prevent possibility that freedom vanishes somewhere in the distribution chain and the user can't benefit from the free software albeit the software is build on originally free source code</li> |
19 non-free software can not be trusted |
22 </ul> |
20 must be buildable using free software toolchain (like GNU/Linux + GNU GCC or OpenJDK etc.) |
23 |
21 should not promote non-free (proprietary) software or services |
24 <h2>Documented</h2> |
22 copyleft licenses (like GNU GPL or GNU Affero GPL) are recommended because they guarantee software freedoms to every single end-user and prevent possibility that freedom vanishes somewhere in the distribution chain a user can't benefit from the free software albeit the software is build on originally free source code |
25 <ul> |
23 |
26 <li>at least basic documentation must be released under a free license (GNU FDL is recommended)</li> |
24 <h2>documented</h2> |
27 <li>there might be also other documentation/books released under any license and price</li> |
25 at least basic documentation must be released under a free license (GNU FDL is recommended) |
28 <li>but average software engineer must be able to build and operate the software with just the basic free documentation</li> |
26 there might be also other documentation/books released under any license and price |
29 <li>there must be a free documentation describing building and running of the software on a fresh operating system installation including description of all dependencies</li> |
27 but average software engineer must be able to build and operate the software with just basic free documentation |
30 <li>documentation should focus on all target groups: users, administrators, developers</li> |
28 there must be a free documentation describing building and running of the software on a fresh operating system installation including description of all dependencies |
31 <li>there must be a big picture and software architercure described</li> |
29 documentation should focus on all target groups: users, administrators, developers |
32 </ul> |
30 there must be a big picture and software architercure described |
|
31 |
33 |
32 <h2>semantic versioning</h2> |
34 <h2>Semantic versioning</h2> |
33 strongly recommended |
35 <ul> |
34 required when the package is suposed to be used as dependency by others |
36 <li>strongly recommended</li> |
35 if there is need of some marketing or cool versioning/codenames like Ultrasonic Umbrella or 2016, they should be used in addition to semantic versioning, not instead it |
37 <li>required when the package is suposed to be used as dependency by others</li> |
36 once publicly released, the package must not be changed anymore – if a change (even small fix) is needed, new version number must be assigned |
38 <li>if there is need of some marketing or cool versioning/codenames like Ultrasonic Umbrella or 2016, they should be used in addition to semantic versioning, not instead it</li> |
37 APIs, file formats and protocols might be semanticly versioned independently from the implementation |
39 <li>once publicly released, the package must not be changed anymore – if a change (even small fix) is needed, new version number must be assigned</li> |
38 in such case, there should be a table documenting which API/format/protocol version matches which implementation version |
40 <li> |
39 |
41 APIs, file formats and protocols might be semanticly versioned independently from the implementation; |
40 <h2>compatibilible with itself</h2> |
42 in such case, there should be a table documenting which API/format/protocol version matches which implementation version |
41 focus on backward compatibility |
43 </li> |
42 don't broke things |
44 </ul> |
43 incompatible changes must be planned and announced in advance |
45 |
44 upgrade scripts + upgrade documentation |
46 <h2>Compatibilible with itself</h2> |
45 |
47 <ul> |
46 <h2>compatibilible with others</h2> |
48 <li>focus on backward compatibility</li> |
47 use open standards (protocols, formats) if they exist |
49 <li>don't broke things</li> |
48 define own open standards if needed |
50 <li>incompatible changes must be planned and announced in advance</li> |
49 also standards must be semantically versioned |
51 <li>upgrade scripts + upgrade documentation</li> |
50 should be written in machine readable format (WSDL, WADL, ASN.1, XSD, Diameter dictionary etc.) or at least formal language (Backus–Naur Form, EBNF etc.) |
52 </ul> |
51 also configuration should have machine readable description and should be testable by executing a command |
53 |
52 |
54 <h2>Compatibilible with others</h2> |
53 <h2>modular architecture</h2> |
55 <ul> |
54 larger and multi-purpose software should be divided into smaller modules |
56 <li>use open standards (protocols, formats) if they exist</li> |
55 modules must have defined dependencies (less = better) |
57 <li>define own open standards if needed |
56 particular modules should be compilable and executable separately |
58 <ul> |
57 whole system should be compilable with only selected modules – must not require compilation or even distribution of all modules, if they are not necessary |
59 <li>also standards must be semantically versioned</li> |
58 |
60 <li>should be written in machine readable format (WSDL, WADL, ASN.1, XSD, Diameter dictionary etc.) or at least formal language (Backus–Naur Form, EBNF etc.)</li> |
59 <h2>extensible</h2> |
61 <li>also configuration should have machine readable description and should be testable by executing a command</li> |
60 able to be extended |
62 </ul> |
61 by configuration (RegExp, SQL, XSLT, XPath etc.) |
63 </li> |
62 by scripting (Guile, ECMA Script etc.) |
64 </ul> |
63 and/or third-party plugins/modules |
65 |
64 it should be easy to create a third-party module and plug it in an existing system |
66 <h2>Modular architecture</h2> |
65 dependencies needed to write an extension (i.e. header files, API classes/interfaces) should be as small as possible (do not require large codebase to write an extension) |
67 <ul> |
66 there should be public directory of extensions/scripts |
68 <li>larger and multi-purpose software should be divided into smaller modules</li> |
67 |
69 <li>modules must have defined dependencies (less = better)</li> |
68 <h2>testable</h2> |
70 <li>particular modules should be compilable and executable separately</li> |
69 there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output |
71 <li>whole system should be compilable (buildable) with only selected modules – must not require compilation or even distribution of all modules, if they are not necessary</li> |
70 there should be also automated runtime/postinstall tests – in order to verify that software was installed properly, all required dependencies are met and basic function is guaranteed – the program should report problem during its start (as a warning if it is not fatal), instead of unexpected failures during operation |
72 </ul> |
71 unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces |
73 |
72 |
74 <h2>Extensible</h2> |
73 <h2>safe code and sustainability</h2> |
75 |
74 correctness, safety and readability is prefered to performance |
76 <ul> |
75 use strong data typing, declare preconditions and possible exceptions |
77 <li>able to be extended |
76 data structures must be known and well documented – don't use undocumented map keys or properties |
78 <ul> |
77 code, comments and analysis should be written in the same natural language |
79 <li>by configuration (RegExp, SQL, XSLT, XPath etc.)</li> |
78 there should be a dictionary of used terms, so whole team and also users and customers will speak same language |
80 <li>by scripting (Guile, Bash, ECMA Script etc.)</li> |
79 |
81 <li>and/or third-party plugins/modules |
80 <h2>small code footprint</h2> |
82 <ul> |
81 less LOC (resp. complexity) = better |
83 <li>it should be easy to create a third-party module and plug it in an existing system</li> |
82 reduce boilerplate and unused code |
84 <li>dependencies needed to write an extension (i.e. header files, API classes/interfaces) should be as small as possible (do not require large codebase to write a mere plug-in)</li> |
83 use code generators (during build process, not to generate code to be manually edited and versioned) |
85 </ul> |
84 |
86 </li> |
85 <h2>sane dependencies</h2> |
87 </ul> |
86 avoid NIH and reuse code but also avoid dependency hell |
88 </li> |
87 know your dependencies, know why they are required |
89 <li>there should be public directory of extensions/scripts</li> |
88 reduce dependencies to only necessary ones |
90 </ul> |
89 depend on small and useful libraries – not on bulky application packages |
91 |
90 if dependency on bulky application package is inevitable, add a layer of abstraction – create a generic interface and connector and allow others to replace the bulky package with their own sane implementation |
92 <h2>Testable</h2> |
91 helper tools: |
93 <ul> |
92 if you e.g. use Bash and Perl during the build process, don't add also Python dependency, write it in Perl – or use Python instead of Perl. |
94 <li>there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output</li> |
93 Or if you use Java as your main language, consider not using Python/Perl for scripting and use Java for it |
95 <li>there should be also automated runtime/postinstall tests – in order to verify that software was installed properly, all required dependencies are met and basic function is guaranteed – the program should report problem during its start (as a warning if it is not fatal), instead of unexpected failures during operation</li> |
94 if possible, always depend on abstract interfaces, not on particular implementations |
96 <li>unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces</li> |
95 |
97 </ul> |
96 <h2>easily auditable</h2> |
98 |
97 small code footprint and minimal dependencies makes it easy to do security audit |
99 <h2>Safe code and sustainability</h2> |
98 avoid ungrounded refactoring and reformatting – they make mess and noise in the version control system and impede the audit |
100 <ul> |
99 refactoring/reformatting changesets should be separated from substantive changes |
101 <li>correctness, safety and readability is prefered to performance</li> |
100 |
102 <li>use strong data typing, declare preconditions and possible exceptions</li> |
101 <h2>reproducible builds</h2> |
103 <li>data structures must be known and well documented – don't use undocumented map keys or properties</li> |
102 builds should be reproducible: same code/version → same binary package |
104 <li>code, comments and analysis should be written in the same natural language</li> |
103 if not, it should be documented, why and how build products mihgt differ, and there should be plan/task to make it reproducible |
105 <li>there should be a dictionary of used terms, so whole team and also users and customers will speak same language</li> |
104 |
106 </ul> |
105 <h2>trustworthy packages and sources</h2> |
107 |
106 every released version (binary or source) is cryptographically signed by the authors (GnuPG/OpenPGP is strongly recommended) |
108 <h2>Small code footprint</h2> |
107 if HTTP is supported, HTTPS should also be – the attacker/eavesdropper should not even know what software/package/update is downloaded by the user |
109 <ul> |
108 the attacker should not be able to suppress updates – the program must not be silent in such case and must warn the user that something possibly nasty and dangerous is happening |
110 <li>less LOC (resp. complexity) = better</li> |
109 releases should be downloadable also (or exclusively) over BitTorrent or other P2P network |
111 <li>reduce boilerplate and unused code</li> |
110 there should be also checksums/hashes for every package |
112 <li>use code generators (during build process, not to generate code to be manually edited and versioned)</li> |
111 source code repository is accessible through an encrypted connection |
113 </ul> |
112 |
114 |
113 <h2>network interactions</h2> |
115 <h2>Sane dependencies</h2> |
114 no network connection is needed during build – build must be possible completely offline, all dependencies must be downloadable and documented including secure hashes or better cryptographic signatures |
116 <ul> |
115 if dependencies are optionally automatically downloaded during/before build, the packaging system must cryptographically verify that that they are undamaged |
117 <li>avoid NIH and reuse code but also avoid dependency hell</li> |
116 avoid unwanted network interactions during runtime – no „call home“ or update-checks without user's explicit consent |
118 <li>know your dependencies, know why they are required</li> |
117 if any network connection is used, it must be cryptographically secured against MITM attacks |
119 <li>reduce dependencies to only necessary ones</li> |
118 |
120 <li>depend on small and useful libraries – not on bulky application packages</li> |
119 <h2>localized/internationalized</h2> |
121 <li>if dependency on bulky application package is inevitable, add a layer of abstraction – create a generic interface and connector and allow others to replace the bulky package with their own sane implementation</li> |
120 is is strongly recommended that it should be possible to localize the user interface independently from the original author by writing a language pack |
122 <li>helper tools: |
121 GNU Gettext or other standard framework (like Java resource bundles) should be used |
123 <ul> |
122 error messages should have assigned unique error codes, so it is possible to find relevant information regardless current locale |
124 <li>if you e.g. use Bash and Perl during the build process, don't add also Python dependency, write it in Perl – or use Python instead of Perl.</li> |
123 GEC is recommended for such unique error identifiers |
125 <li>Or if you use Java as your main language, consider not using Python/Perl for scripting and use Java for it</li> |
124 data formats and protocols must be language/locale independent |
126 </ul> |
125 e.g. use decimal point instead of comma and no thousand separators for numbers, use standardized date formats |
127 </li> |
126 in general: everything that is expected to be machine-readable or machine-generated must be independent from current locale |
128 <li>if possible, always depend on abstract interfaces, not on particular implementations</li> |
127 character encoding: |
129 </ul> |
128 always be aware of it, don't just blindly use current platform's default (because the other side might run on different platform with different default) |
130 |
129 if given software/format/protocol has some default encoding, it must be clearly defined in its specification and this default should not be changed without changing the major version number |
131 <h2>Easily auditable</h2> |
130 if there is no default, the encoding must be specified in the metadata attached (e.g. protocol headers, extended attributes on filesystem) to the actual data or at least at the begining of the data (like declaration in XML format) |
132 <ul> |
131 the metric system should be used as default |
133 <li>small code footprint and minimal dependencies makes it easy to do security audit</li> |
132 |
134 <li>avoid ungrounded refactoring and reformatting – they make mess and noise in the version control system and impede the audit</li> |
133 <h2>communication channels</h2> |
135 <li>refactoring/reformatting changesets should be separated from substantive changes</li> |
134 RSS/Atom or other machine readable format for: |
136 </ul> |
135 security announcements |
137 |
136 new version announcements |
138 <h2>Reproducible builds</h2> |
137 infrastructure outage announcements |
139 <ul> |
138 blog, documentation, how-tos etc. |
140 <li>builds should be reproducible: same code/version → same binary package</li> |
139 AFK events (conferences, meetings, hackatons etc.), for calendar data iCal format is strongly recommended |
141 <li>if not, it should be documented, why and how build products mihgt differ, and there should be plan/task to make it reproducible</li> |
140 mailing list |
142 </ul> |
141 e-mail/smtp |
143 |
142 use TLS |
144 <h2>Trustworthy packages and sources</h2> |
143 use DKIM/ADSP |
145 <ul> |
144 use signed and encrypted messages (GnuPG or X.509) |
146 <li>every released version (binary or source) is cryptographically signed by the authors (GnuPG/OpenPGP is strongly recommended)</li> |
145 avoid spam and viruses, don't spam the users, don't push them to subscribe your „newsletter“ – always offer also anonymous channel like RSS/Atom |
147 <li>if HTTP is supported, HTTPS should also be – the attacker/eavesdropper should not even know what software/package/update is downloaded by the user</li> |
146 Jabber MUC or IRC |
148 <li>the attacker should not be able to suppress updates – the program must not be silent in such case and must warn the user that something possibly nasty and dangerous is happening </li> |
147 discussion forum |
149 <li>releases should be downloadable also (or exclusively) over BitTorrent or other P2P network</li> |
148 don't push users to register at a proprietary social networks resp. at particular company like Facebook – users without such account must not be discriminated – use open and decentralized networks/protocols instead |
150 <li>there should be also checksums/hashes for every package</li> |
149 Q&A tool + FAQ |
151 <li>source code repository is accessible through an encrypted connection</li> |
150 there should be a second-level internet domain for the project or its team |
152 </ul> |
151 but don't buy an internet domain if you are not prepared to mainain it for decades – rather use third level domain under some reliable second level domain maintained by a credible group or person – think of that every expired domain helps spammers and scammers and hurts the users |
153 |
152 URLs should be as stable as possible (don't broke old links, set up redirections if needed) |
154 <h2>Network interactions</h2> |
153 the website must be independent and must contain everything needed – any content (JavaScripts, CSS, fonts etc.) downloaded from othed domains must not be required to browse/use the website |
155 <ul> |
154 authors should publish their public keys (GnuPG/OpenPGP or X.509) |
156 <li>no network connection is needed during build – build must be possible completely offline, all dependencies must be downloadable and documented including secure hashes or better cryptographic signatures</li> |
155 crpyptographically secured e-mail address or web form for receiving security vulnerabilities report |
157 <li>if dependencies are optionally automatically downloaded during/before build, the packaging system must cryptographically verify that that they are undamaged</li> |
156 every security incident must be clearly documented and investigated – don't obscure it |
158 <li>avoid unwanted network interactions during runtime – no „call home“ or update-checks without user's explicit consent</li> |
157 |
159 <li>if any network connection is used, it must be cryptographically secured against MITM attacks</li> |
158 <h2>open development – has public:</h2> |
160 </ul> |
159 source code repository (versioning system), not just source code releases |
161 |
160 description of the process of accepting external patches |
162 <h2>Localized/internationalized</h2> |
161 feature/bug tracking system |
163 <ul> |
162 roadmap of future releases |
164 <li>is is strongly recommended that it should be possible to localize the user interface independently from the original author by writing a language pack</li> |
163 plan of supported versions/branches |
165 <li>GNU Gettext or other standard framework (like Java resource bundles) should be used</li> |
164 every release/version/branch must clearly declare the status (alpha, beta, prototype, stable, retired, deprecated…) |
166 <li>error messages should have assigned unique error codes, so it is possible to find relevant information regardless current locale</li> |
|
167 <!-- GEC is recommended for such unique error identifiers --> |
|
168 <li>data formats and protocols must be language/locale independent |
|
169 <ul> |
|
170 <li>e.g. use decimal point instead of comma and no thousand separators for numbers, use standardized date formats</li> |
|
171 <li>in general: everything that is expected to be machine-readable or machine-generated must be independent from current locale</li> |
|
172 </ul> |
|
173 </li> |
|
174 <li>character encoding: |
|
175 <ul> |
|
176 <li>always be aware of it, don't just blindly use current platform's default (because the other side might run on different platform with different default)</li> |
|
177 <li>if given software/format/protocol has some default encoding, it must be clearly defined in its specification and this default should not be changed without changing the major version number</li> |
|
178 <li>if there is no default, the encoding must be specified in the metadata attached (e.g. protocol headers, extended attributes on filesystem) to the actual data or at least at the begining of the data (like declaration in XML format)</li> |
|
179 </ul> |
|
180 </li> |
|
181 <li>the metric system should be used as default</li> |
|
182 </ul> |
|
183 |
|
184 <h2>Communication channels</h2> |
|
185 <ul> |
|
186 <li>use RSS/Atom or other machine readable format for: |
|
187 <ul> |
|
188 <li>security announcements</li> |
|
189 <li>new version announcements</li> |
|
190 <li>infrastructure outage announcements</li> |
|
191 <li>blog, documentation, how-tos etc.</li> |
|
192 <li>AFK events (conferences, meetings, hackatons etc.), for calendar data iCal format is strongly recommended</li> |
|
193 </ul> |
|
194 </li> |
|
195 <li>mailing list</li> |
|
196 <li>e-mail/SMTP |
|
197 <ul> |
|
198 <li>use TLS</li> |
|
199 <li>use DKIM/ADSP</li> |
|
200 <li>use signed and encrypted messages (GnuPG or X.509)</li> |
|
201 <li>avoid spam and viruses, don't spam the users, don't push them to subscribe your „newsletter“ – always offer also anonymous channel like RSS/Atom</li> |
|
202 </ul> |
|
203 </li> |
|
204 <li>Jabber MUC or IRC</li> |
|
205 <li>discussion forum</li> |
|
206 <li>don't push users to register at a proprietary social networks resp. at particular company like Facebook – users without such account must not be discriminated – use open and decentralized networks/protocols instead</li> |
|
207 <li>Q&A tool + FAQ</li> |
|
208 <li>there should be a second-level internet domain for the project or its team</li> |
|
209 <li>but don't buy an internet domain if you are not prepared to mainain it for decades – rather use third level domain under some reliable second level domain maintained by a credible group or person – think of that every expired domain helps spammers and scammers and hurts the users</li> |
|
210 <li>URLs should be as stable as possible (don't broke old links, set up redirections if needed)</li> |
|
211 <li>the website must be independent and must contain everything needed – any content (JavaScripts, CSS, fonts, images etc.) downloaded from other domains must not be required to browse/use the website</li> |
|
212 <li>authors should publish their public keys (GnuPG/OpenPGP or X.509)</li> |
|
213 <li>crpyptographically secured e-mail address or web form for receiving security vulnerabilities report</li> |
|
214 <li>every security incident must be clearly documented and investigated – don't obscure it</li> |
|
215 </ul> |
|
216 |
|
217 <h2>Open development – has public:</h2> |
|
218 <ul> |
|
219 <li>source code repository (versioning system), not just source code releases</li> |
|
220 <li>description of the process of accepting external patches</li> |
|
221 <li>feature/bug tracking system</li> |
|
222 <li>roadmap of future releases</li> |
|
223 <li>plan of supported versions/branches</li> |
|
224 <li>every release/version/branch must clearly declare the status (alpha, beta, prototype, stable, retired, deprecated…)</li> |
|
225 </ul> |
165 |
226 |
166 |
227 |
167 </body> |
228 </body> |
168 </html> |
229 </html> |