5 <title>Sane Software Manifesto</title> |
5 <title>Sane Software Manifesto</title> |
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 style="text-align: center"><DRAFT> Please note that this is a draft version. Stay tuned for v1.0.0! </DRAFT></p> |
11 <p style="text-align: center"><DRAFT> Please note that this is a draft version. Stay tuned for v1.0.0! </DRAFT></p> |
12 |
12 |
13 <p>In respect to user freedoms, privacy, liberty, quality, mental health and world peace we create software according to these guidelines.</p> |
13 <p>In respect to user freedoms, privacy, liberty, quality, mental health and world peace we create software according to these guidelines.</p> |
14 |
14 |
15 <h2>Free software</h2> |
15 <h2>Free software</h2> |
16 |
16 |
17 <ul> |
17 <ul> |
18 <li>Every piece of Sane software is also <a href="https://www.gnu.org/philosophy/free-sw.html">Free software</a>.</li> |
18 <li>Every piece of Sane software is also <a href="https://www.gnu.org/philosophy/free-sw.html">Free software</a>.</li> |
19 <li>The user has freedom to run the program for any purpose, to study and change it (i.e. has access to the source code under a free software license) and to distribute modified or unmodified copies.</li> |
19 <li>The user has freedom to run the program for any purpose, to study and change it (i.e. has access to the source code under a free software license) and to distribute modified or unmodified copies.</li> |
20 <li>The user controls his/her computer and software and owns the data.</li> |
20 <li>The user controls his/her computer and software and owns the data.</li> |
21 <li>Non-free software can not be trusted.</li> |
21 <li>Non-free software can not be trusted.</li> |
35 <!-- |
35 <!-- |
36 <li>documentation should focus on all target groups: users, administrators, developers</li> |
36 <li>documentation should focus on all target groups: users, administrators, developers</li> |
37 <li>there must be a big picture and software architercure described</li> |
37 <li>there must be a big picture and software architercure described</li> |
38 --> |
38 --> |
39 </ul> |
39 </ul> |
40 |
40 |
41 <h2>Semantic versioning</h2> |
41 <h2>Semantic versioning</h2> |
42 <ul> |
42 <ul> |
43 <li><a href="http://semver.org/">Semantic versioning</a> is strongly recommended.</li> |
43 <li><a href="http://semver.org/">Semantic versioning</a> is strongly recommended.</li> |
44 <li>Especially when the software is suposed to be used as dependency by others.</li> |
44 <li>Especially when the software is suposed to be used as dependency by others.</li> |
45 <li>If there is a need of some marketing or cool versioning/codenames like Ultrasonic Umbrella or 2016, they should be used in addition to semantic versioning, not instead of it.</li> |
45 <li>If there is a need of some marketing or cool versioning/codenames like Ultrasonic Umbrella or 2016, they should be used in addition to semantic versioning, not instead of it.</li> |
62 <h2>Compatible with others</h2> |
62 <h2>Compatible with others</h2> |
63 <ul> |
63 <ul> |
64 <li>use open standards (protocols, formats) if they exist</li> |
64 <li>use open standards (protocols, formats) if they exist</li> |
65 <li>define and publish own open standards if needed |
65 <li>define and publish own open standards if needed |
66 <ul> |
66 <ul> |
67 <li>also standards must be semantically versioned</li> |
67 <li>also standards must be semantically versioned</li> |
68 <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> |
68 <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> |
69 <li>also configuration should have machine readable description and should be testable by executing a command</li> |
69 <li>also configuration should have machine readable description and should be testable by executing a command</li> |
70 </ul> |
70 </ul> |
71 </li> |
71 </li> |
72 </ul> |
72 </ul> |
73 |
73 |
74 <h2>Modular architecture</h2> |
74 <h2>Modular architecture</h2> |
81 |
81 |
82 <h2>Extensible</h2> |
82 <h2>Extensible</h2> |
83 |
83 |
84 <ul> |
84 <ul> |
85 <li>able to be extended |
85 <li>able to be extended |
86 <ul> |
86 <ul> |
87 <li>by configuration (RegExp, SQL, XSLT, XPath etc.)</li> |
87 <li>by configuration (RegExp, SQL, XSLT, XPath etc.)</li> |
88 <li>by scripting (Guile, Bash, Python, Lua, ECMA Script etc.)</li> |
88 <li>by scripting (Guile, Bash, Python, Lua, ECMA Script etc.)</li> |
89 <li>and/or third-party plugins/modules |
89 <li>and/or third-party plugins/modules |
90 <ul> |
90 <ul> |
91 <li>it should be easy to create a third-party module and plug it in an existing system</li> |
91 <li>it should be easy to create a third-party module and plug it in an existing system</li> |
92 <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); the required dependency should contain just interfaces (method/function signatures) and data structures but no implementation (executable code)</li> |
92 <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); the required dependency should contain just interfaces (method/function signatures) and data structures but no implementation (executable code)</li> |
93 </ul> |
93 </ul> |
94 </li> |
94 </li> |
95 </ul> |
95 </ul> |
96 </li> |
96 </li> |
97 <li>there should be public directory of extensions/scripts</li> |
97 <li>there should be public directory of extensions/scripts</li> |
98 </ul> |
98 </ul> |
99 |
99 |
100 <h2>Testable</h2> |
100 <h2>Testable</h2> |
128 <li>know your dependencies, know why they are required</li> |
128 <li>know your dependencies, know why they are required</li> |
129 <li>reduce dependencies to only necessary ones</li> |
129 <li>reduce dependencies to only necessary ones</li> |
130 <li>depend on small and useful libraries – not on bulky application packages or libraries with large transitive dependencies</li> |
130 <li>depend on small and useful libraries – not on bulky application packages or libraries with large transitive dependencies</li> |
131 <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> |
131 <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> |
132 <li>helper tools: |
132 <li>helper tools: |
133 <ul> |
133 <ul> |
134 <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> |
134 <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> |
135 <li>Or if you use Java as your main language, consider not using Python/Perl for scripting and use Java for it</li> |
135 <li>Or if you use Java as your main language, consider not using Python/Perl for scripting and use Java for it</li> |
136 </ul> |
136 </ul> |
137 </li> |
137 </li> |
138 <li>if possible, always depend on abstract interfaces, not on particular implementations</li> |
138 <li>if possible, always depend on abstract interfaces, not on particular implementations</li> |
139 </ul> |
139 </ul> |
140 |
140 |
141 <h2>Easily auditable</h2> |
141 <h2>Easily auditable</h2> |
174 <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> |
174 <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> |
175 <li>GNU Gettext or other standard framework (like Java resource bundles) should be used</li> |
175 <li>GNU Gettext or other standard framework (like Java resource bundles) should be used</li> |
176 <li>error messages should have assigned unique error codes, so it is possible to find relevant information regardless current locale</li> |
176 <li>error messages should have assigned unique error codes, so it is possible to find relevant information regardless current locale</li> |
177 <!-- GEC is recommended for such unique error identifiers --> |
177 <!-- GEC is recommended for such unique error identifiers --> |
178 <li>data formats and protocols must be language/locale independent |
178 <li>data formats and protocols must be language/locale independent |
179 <ul> |
179 <ul> |
180 <li>e.g. use decimal point instead of comma and no thousand separators for numbers, use standardized date formats</li> |
180 <li>e.g. use decimal point instead of comma and no thousand separators for numbers, use standardized date formats</li> |
181 <li>in general: everything that is expected to be machine-readable or machine-generated must be independent from current locale</li> |
181 <li>in general: everything that is expected to be machine-readable or machine-generated must be independent from current locale</li> |
182 </ul> |
182 </ul> |
183 </li> |
183 </li> |
184 <li>character encoding: |
184 <li>character encoding: |
185 <ul> |
185 <ul> |
186 <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> |
186 <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> |
187 <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> |
187 <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> |
188 <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> |
188 <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> |
189 </ul> |
189 </ul> |
190 </li> |
190 </li> |
191 <li>the metric system should be used as default</li> |
191 <li>the metric system should be used as default</li> |
192 </ul> |
192 </ul> |
193 |
193 |
194 <h2>Communication channels</h2> |
194 <h2>Communication channels</h2> |
195 <ul> |
195 <ul> |
196 <li>use RSS/Atom or other machine readable format for: |
196 <li>use RSS/Atom or other machine readable format for: |
197 <ul> |
197 <ul> |
198 <li>security announcements</li> |
198 <li>security announcements</li> |
199 <li>new version announcements</li> |
199 <li>new version announcements</li> |
200 <li>infrastructure outage announcements</li> |
200 <li>infrastructure outage announcements</li> |
201 <li>blog, documentation, how-tos etc.</li> |
201 <li>blog, documentation, how-tos etc.</li> |
202 <li>AFK events (conferences, meetings, hackatons etc.), for calendar data iCal format is strongly recommended</li> |
202 <li>AFK events (conferences, meetings, hackatons etc.), for calendar data iCal format is strongly recommended</li> |
203 </ul> |
203 </ul> |
204 </li> |
204 </li> |
205 <li>mailing list</li> |
205 <li>mailing list</li> |
206 <li>e-mail/SMTP |
206 <li>e-mail/SMTP |
207 <ul> |
207 <ul> |
208 <li>use TLS</li> |
208 <li>use TLS</li> |
209 <li>use DKIM/ADSP</li> |
209 <li>use DKIM/ADSP</li> |
210 <li>use signed and encrypted messages (GnuPG or X.509)</li> |
210 <li>use signed and encrypted messages (GnuPG or X.509)</li> |
211 <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> |
211 <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> |
212 </ul> |
212 </ul> |
213 </li> |
213 </li> |
214 <li>Jabber MUC or IRC</li> |
214 <li>Jabber MUC or IRC</li> |
215 <li>discussion forum</li> |
215 <li>discussion forum</li> |
216 <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> |
216 <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> |
217 <li>Q&A tool + FAQ</li> |
217 <li>Q&A tool + FAQ</li> |
222 <li>authors should publish their public keys (GnuPG/OpenPGP or X.509)</li> |
222 <li>authors should publish their public keys (GnuPG/OpenPGP or X.509)</li> |
223 <li>crpyptographically secured e-mail address or web form for receiving security vulnerabilities report</li> |
223 <li>crpyptographically secured e-mail address or web form for receiving security vulnerabilities report</li> |
224 <li>every security incident must be clearly documented and investigated – don't obscure it</li> |
224 <li>every security incident must be clearly documented and investigated – don't obscure it</li> |
225 </ul> |
225 </ul> |
226 |
226 |
|
227 <h2>Accept contributions</h2> |
|
228 <ul> |
|
229 <li>good quality code contributions with appropriate copyright and patent licenses or assignments should be accepted from anyone</li> |
|
230 <li>the <em>good quality code</em> is defined by the project and might involve code style, idioms, design patterns, software architecture, required tests, documentation etc.</li> |
|
231 <li>such requirements and rules should be available to the contributor before he begins; however (especially smaller) projects might communicate such code quality requirements and provide consultations and guidance during the contribution</li> |
|
232 <li>in order to contribute, it must not be required: |
|
233 <ul> |
|
234 <li>to have an account on any particular third party service like particular e-mail or hosting provider</li> |
|
235 <li>to sign a contract (which includes accepting <em>Terms and conditions</em>) with any particular third party (e.g. source code hosting provider)</li> |
|
236 <li>to sign any political, religious or other proclamation or agree with it</li> |
|
237 </ul> |
|
238 </li> |
|
239 <li>in order to contribute, it might be required: |
|
240 <ul> |
|
241 <li>to have an e-mail address (but not at particular domain)</li> |
|
242 <li>to assign the copyright to the project and grant a free license for all patents relevant to the contribution</li> |
|
243 </ul> |
|
244 </li> |
|
245 <li>the project should record all accepted contributions and maintain a public list of all authors/contributors</li> |
|
246 <li>the contributor must not loose the right to use or distribute the contributed code under any license (of his choice)</li> |
|
247 </ul> |
|
248 |
227 <h2>Open development – has public:</h2> |
249 <h2>Open development – has public:</h2> |
228 <ul> |
250 <ul> |
229 <li>source code repository (versioning system), not just source code releases</li> |
251 <li>source code repository (versioning system), not just source code releases</li> |
230 <li>description of the process of accepting external patches</li> |
252 <li>description of the process of accepting external patches</li> |
231 <li>feature/bug tracking system</li> |
253 <li>feature/bug tracking system</li> |
232 <li>roadmap of future releases</li> |
254 <li>roadmap of future releases</li> |
233 <li>plan of supported versions/branches</li> |
255 <li>plan of supported versions/branches</li> |
234 <li>every release/version/branch must clearly declare the status (alpha, beta, prototype, stable, retired, deprecated…)</li> |
256 <li>every release/version/branch must clearly declare the status (alpha, beta, prototype, stable, retired, deprecated…)</li> |
235 </ul> |
257 </ul> |
236 |
258 |
237 |
259 |
238 </body> |
260 </body> |
239 </html> |
261 </html> |