24 <item> |
24 <item> |
25 <id>a755410b-6264-4094-b339-aeca55448e8d</id> |
25 <id>a755410b-6264-4094-b339-aeca55448e8d</id> |
26 <text>Every piece of Sane software is also Free software (as originally defined by Richard Stallman).</text> |
26 <text>Every piece of Sane software is also Free software (as originally defined by Richard Stallman).</text> |
27 <text>Which means that the user has freedom to</text> |
27 <text>Which means that the user has freedom to</text> |
28 <text>run the program for any purpose,</text> |
28 <text>run the program for any purpose,</text> |
29 <text>to study and change it (i.e. has access to the source code under a free software license)</text> |
29 <text>to study and change it (i.e. has access to the source code under a free software license)</text> |
30 <text>and to distribute modified or unmodified copies.</text> |
30 <text>and to distribute modified or unmodified copies.</text> |
31 <note>see https://www.gnu.org/philosophy/free-sw.html</note> |
31 <note>see https://www.gnu.org/philosophy/free-sw.html</note> |
32 <note>see https://www.gnu.org/philosophy/who-does-that-server-really-serve.html</note> |
32 <note>see https://www.gnu.org/philosophy/who-does-that-server-really-serve.html</note> |
33 </item> |
33 </item> |
34 <item> |
34 <item> |
57 <!-- TODO: provide exact wording of the exception e.g. XYZ is „Sane software (with GPLv2 license exception)“ --> |
57 <!-- TODO: provide exact wording of the exception e.g. XYZ is „Sane software (with GPLv2 license exception)“ --> |
58 <note>Software versioned under GPLv2+ or GPLv3+ is compatible with GPLv3.</note> |
58 <note>Software versioned under GPLv2+ or GPLv3+ is compatible with GPLv3.</note> |
59 </item> |
59 </item> |
60 <item> |
60 <item> |
61 <id>f39b90ae-0054-467e-a9e2-43379b7c2331</id> |
61 <id>f39b90ae-0054-467e-a9e2-43379b7c2331</id> |
62 <text>If the software is distributed with a hardware, the hardware must support instalation of independently built software without any restrictions or requirements (e.g. digital signature from the original author).</text> |
62 <text>If the software is distributed with a hardware, the hardware must support instalation of independently built software without any restrictions or requirements (e.g. digital signature from the original author).</text> |
63 </item> |
63 </item> |
64 </chapter> |
64 </chapter> |
65 |
65 |
66 <chapter> |
66 <chapter> |
67 <name>Documented</name> |
67 <name>Documented</name> |
68 <id>e1c828c5-0a4f-4948-9943-db1ae16a42d5</id> |
68 <id>e1c828c5-0a4f-4948-9943-db1ae16a42d5</id> |
69 <item> |
69 <item> |
70 <id>c63ea2ac-c255-4f3e-a0e2-b49d1e145347</id> |
70 <id>c63ea2ac-c255-4f3e-a0e2-b49d1e145347</id> |
71 <text>At least basic documentation must be released under a free license (GNU FDL is recommended).</text> |
71 <text>At least basic documentation must be released under a free license (GNU FDL is recommended).</text> |
72 </item> |
72 </item> |
73 <item> |
73 <item> |
74 <id>fd8e3bbd-d46a-40fe-85a6-b902336456d4</id> |
74 <id>fd8e3bbd-d46a-40fe-85a6-b902336456d4</id> |
75 <text>Every advertised feature must be properly documented. Undocumented features can not be considered as features from the user/customer point-of-view.</text> |
75 <text>Every advertised feature must be properly documented. Undocumented features can not be considered as features from the user/customer point-of-view.</text> |
76 </item> |
76 </item> |
82 <id>c0df4d14-43f8-4b61-83c4-fb5896161aeb</id> |
82 <id>c0df4d14-43f8-4b61-83c4-fb5896161aeb</id> |
83 <text>But average software engineer must be able to build and operate the software with just the free (basic) documentation.</text> |
83 <text>But average software engineer must be able to build and operate the software with just the free (basic) documentation.</text> |
84 </item> |
84 </item> |
85 <item> |
85 <item> |
86 <id>e6cd9c52-0e66-402c-930c-901fa66acd22</id> |
86 <id>e6cd9c52-0e66-402c-930c-901fa66acd22</id> |
87 <text>There must be a free documentation with description of building and running the software on a fresh operating system installation including description of all dependencies.</text> |
87 <text>There must be a free documentation with description of building and running the software on a fresh operating system installation including description of all dependencies.</text> |
88 </item> |
88 </item> |
89 <!-- |
89 <!-- |
90 <item><id></id><text>documentation should focus on all target groups: users, administrators, developers</text></item> |
90 <item><id></id><text>documentation should focus on all target groups: users, administrators, developers</text></item> |
91 <item><id></id><text>there must be a big picture and software architercure described</text></item> |
91 <item><id></id><text>there must be a big picture and software architercure described</text></item> |
92 --> |
92 --> |
93 </chapter> |
93 </chapter> |
94 |
94 |
95 <chapter> |
95 <chapter> |
96 <name>Semantic versioning and upgrades</name> |
96 <name>Semantic versioning and upgrades</name> |
98 <item> |
98 <item> |
99 <id>a8beddfc-11e3-4012-9f88-f79dc88eee16</id> |
99 <id>a8beddfc-11e3-4012-9f88-f79dc88eee16</id> |
100 <text>Semantic versioning is required.</text> |
100 <text>Semantic versioning is required.</text> |
101 <text>The version number consists of three numbers: major.minor.pach.</text> |
101 <text>The version number consists of three numbers: major.minor.pach.</text> |
102 <text>Major version is incremented if there is an incompatible change.</text> |
102 <text>Major version is incremented if there is an incompatible change.</text> |
103 <text>Minor version is incremented if a feature is added in a compatible way.</text> |
103 <text>Minor version is incremented if a feature is added in a compatible way.</text> |
104 <text>Patch version is incremented if a bug is fixed in a compatible way.</text> |
104 <text>Patch version is incremented if a bug is fixed in a compatible way.</text> |
105 <note>see http://semver.org/</note> |
105 <note>see http://semver.org/</note> |
106 <note>If authors are unable to distinguish between compatible and incompatible changes, they must always increment the major version. However this approach is not recommeded</note> |
106 <note>If authors are unable to distinguish between compatible and incompatible changes, they must always increment the major version. However this approach is not recommeded</note> |
107 <note>Propper Semantic versioning is especially important if the software is suposed to be used as dependency by others.</note> |
107 <note>Propper Semantic versioning is especially important if the software is suposed to be used as dependency by others.</note> |
108 <note>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.</note> |
108 <note>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.</note> |
109 </item> |
109 </item> |
110 <item> |
110 <item> |
111 <id>cf557a11-b307-4c2f-a7b5-5d2485d23258</id> |
111 <id>cf557a11-b307-4c2f-a7b5-5d2485d23258</id> |
112 <text>Once publicly released, the package must not be changed anymore – if a change (even a small fix) is needed, new version number must be assigned.</text> |
112 <text>Once publicly released, the package must not be changed anymore – if a change (even a small fix) is needed, new version number must be assigned.</text> |
113 </item> |
113 </item> |
114 <item> |
114 <item> |
115 <id>dd013325-bf22-43d3-9579-0e272e2ac344</id> |
115 <id>dd013325-bf22-43d3-9579-0e272e2ac344</id> |
116 <text>APIs, file formats and protocols might (and usually should) be semanticly versioned independently from the implementation.</text> |
116 <text>APIs, file formats and protocols might (and usually should) be semanticly versioned independently from the implementation.</text> |
117 <note>In such case, there should be a table documenting which API/format/protocol version matches which implementation version.</note> |
117 <note>In such case, there should be a table documenting which API/format/protocol version matches which implementation version.</note> |
118 </item> |
118 </item> |
119 <item> |
119 <item> |
120 <id>dacb98cc-b558-4f0e-942d-e12004e45606</id> |
120 <id>dacb98cc-b558-4f0e-942d-e12004e45606</id> |
121 <text>The branching model in the version control system should reflect the semantic versioning.</text> |
121 <text>The branching model in the version control system should reflect the semantic versioning.</text> |
122 <text>The released version e.g. 2.3.1 should be tagged as v2.3.1 and be placed in the v_2.3 branch.</text> |
122 <text>The released version e.g. 2.3.1 should be tagged as v2.3.1 and be placed in the v_2.3 branch.</text> |
147 <id>be4c72d1-c494-4c44-aeb4-c5847f5a3524</id> |
147 <id>be4c72d1-c494-4c44-aeb4-c5847f5a3524</id> |
148 <text>Open standards (protocols, formats) should be used if they exist.</text> |
148 <text>Open standards (protocols, formats) should be used if they exist.</text> |
149 </item> |
149 </item> |
150 <item> |
150 <item> |
151 <id>b2202690-8a6c-467f-a2b1-b154f470aa77</id> |
151 <id>b2202690-8a6c-467f-a2b1-b154f470aa77</id> |
152 <text>Already existing open protocol/format must not be modified or extended in a way which effectively creates a proprietary protocol/format.</text> |
152 <text>Already existing open protocol/format must not be modified or extended in a way which effectively creates a proprietary protocol/format.</text> |
153 </item> |
153 </item> |
154 <item> |
154 <item> |
155 <id>dd206223-9525-4229-be2b-84b07c2b8244</id> |
155 <id>dd206223-9525-4229-be2b-84b07c2b8244</id> |
156 <text>New open standards (specifications) should be defined and published if needed.</text> |
156 <text>New open standards (specifications) should be defined and published if needed.</text> |
157 <text>Such standards must be semantically versioned.</text> |
157 <text>Such standards must be semantically versioned.</text> |
160 <id>d341b78e-15b9-4077-8b48-9e54c93391ac</id> |
160 <id>d341b78e-15b9-4077-8b48-9e54c93391ac</id> |
161 <text>And they should be written in machine readable format (e.g. WSDL, WADL, ASN.1, XSD, Diameter dictionary, D-Bus) or at least formal language (Backus–Naur Form, EBNF etc.)</text> |
161 <text>And they should be written in machine readable format (e.g. WSDL, WADL, ASN.1, XSD, Diameter dictionary, D-Bus) or at least formal language (Backus–Naur Form, EBNF etc.)</text> |
162 </item> |
162 </item> |
163 <item> |
163 <item> |
164 <id>d61b3e31-bb9f-4333-87c8-9fb32f33a49d</id> |
164 <id>d61b3e31-bb9f-4333-87c8-9fb32f33a49d</id> |
165 <text>Also configuration should have machine readable description and the user should be able to test it by executing a command (validator).</text> |
165 <text>Also configuration should have machine readable description and the user should be able to test it by executing a command (validator).</text> |
166 </item> |
166 </item> |
167 </chapter> |
167 </chapter> |
168 |
168 |
169 <chapter> |
169 <chapter> |
170 <name>Modular architecture</name> |
170 <name>Modular architecture</name> |
204 <item> |
204 <item> |
205 <id>a9c63cea-b9df-4bbd-bec1-84a047514667</id> |
205 <id>a9c63cea-b9df-4bbd-bec1-84a047514667</id> |
206 <text>and/or third-party plugins/modules</text> |
206 <text>and/or third-party plugins/modules</text> |
207 <item> |
207 <item> |
208 <id>de7270db-0410-4152-974f-4f0d74ff255b</id> |
208 <id>de7270db-0410-4152-974f-4f0d74ff255b</id> |
209 <text>it should be easy to create a third-party module and plug it in an existing system</text> |
209 <text>it should be easy to create a third-party module and plug it in an existing system</text> |
210 </item> |
210 </item> |
211 <item> |
211 <item> |
212 <id>fb4b07d1-6af7-44d9-8e6a-89ea63638652</id> |
212 <id>fb4b07d1-6af7-44d9-8e6a-89ea63638652</id> |
213 <text>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)</text> |
213 <text>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)</text> |
214 </item> |
214 </item> |
215 </item> |
215 </item> |
216 </item> |
216 </item> |
217 <item> |
217 <item> |
218 <id>e41134a4-715c-4926-a7df-01ff3759eda1</id> |
218 <id>e41134a4-715c-4926-a7df-01ff3759eda1</id> |
227 <id>d95dc118-7473-4f18-8b9e-35830a87b269</id> |
227 <id>d95dc118-7473-4f18-8b9e-35830a87b269</id> |
228 <text>there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output</text> |
228 <text>there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output</text> |
229 </item> |
229 </item> |
230 <item> |
230 <item> |
231 <id>a9f6725d-ddf1-41ee-96b4-15f3b851cb50</id> |
231 <id>a9f6725d-ddf1-41ee-96b4-15f3b851cb50</id> |
232 <text>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</text> |
232 <text>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</text> |
233 </item> |
233 </item> |
234 <item> |
234 <item> |
235 <id>d610c04b-cc44-48c7-b069-f41b90bdef0f</id> |
235 <id>d610c04b-cc44-48c7-b069-f41b90bdef0f</id> |
236 <text>unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces</text> |
236 <text>unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces</text> |
237 </item> |
237 </item> |
260 <id>e24e600e-6542-4664-8cf0-2d8c6feb6c13</id> |
260 <id>e24e600e-6542-4664-8cf0-2d8c6feb6c13</id> |
261 <text>code, comments and specification should be written in the same natural language</text> |
261 <text>code, comments and specification should be written in the same natural language</text> |
262 </item> |
262 </item> |
263 <item> |
263 <item> |
264 <id>fa92aa33-a69f-43b8-9051-9bfdcd3d293f</id> |
264 <id>fa92aa33-a69f-43b8-9051-9bfdcd3d293f</id> |
265 <text>there should be a dictionary of used terms, so whole team and also users and customers will speak the same language</text> |
265 <text>there should be a dictionary of used terms, so whole team and also users and customers will speak the same language</text> |
266 </item> |
266 </item> |
267 <item> |
267 <item> |
268 <id>b9345a0e-c672-45d3-b93b-8d0fb4ece8b3</id> |
268 <id>b9345a0e-c672-45d3-b93b-8d0fb4ece8b3</id> |
269 <text>fail fast – errors in the code should be reported during build time or at least on first execution – do not silently continue if given error would lead to failure later in another part of the code – bad weak coupling leads to difficult debugging</text> |
269 <text>fail fast – errors in the code should be reported during build time or at least on first execution – do not silently continue if given error would lead to failure later in another part of the code – bad weak coupling leads to difficult debugging</text> |
270 </item> |
270 </item> |
306 <id>cbeb9a6b-7b64-4452-8caf-246c082a853d</id> |
306 <id>cbeb9a6b-7b64-4452-8caf-246c082a853d</id> |
307 <text>depend on small and useful libraries – not on bulky application packages or libraries with large transitive dependencies</text> |
307 <text>depend on small and useful libraries – not on bulky application packages or libraries with large transitive dependencies</text> |
308 </item> |
308 </item> |
309 <item> |
309 <item> |
310 <id>cbaf55be-8ffb-4109-9c83-083d1b3e793a</id> |
310 <id>cbaf55be-8ffb-4109-9c83-083d1b3e793a</id> |
311 <text>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</text> |
311 <text>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</text> |
312 </item> |
312 </item> |
313 <item> |
313 <item> |
314 <id>d7655989-a5e4-4123-9147-3782fc05a5ee</id> |
314 <id>d7655989-a5e4-4123-9147-3782fc05a5ee</id> |
315 <text>helper tools:</text> |
315 <text>helper tools:</text> |
316 <item> |
316 <item> |
416 <chapter> |
416 <chapter> |
417 <name>Localized/internationalized</name> |
417 <name>Localized/internationalized</name> |
418 <id>fa655b7c-f22d-4b98-ab7b-c0d0f608aad8</id> |
418 <id>fa655b7c-f22d-4b98-ab7b-c0d0f608aad8</id> |
419 <item> |
419 <item> |
420 <id>ad2f572b-497b-4523-b435-f9752fd1518a</id> |
420 <id>ad2f572b-497b-4523-b435-f9752fd1518a</id> |
421 <text>is is strongly recommended that it should be possible to localize the user interface independently from the original author by writing a language pack</text> |
421 <text>is is strongly recommended that it should be possible to localize the user interface independently from the original author by writing a language pack</text> |
422 </item> |
422 </item> |
423 <item> |
423 <item> |
424 <id>c3827486-6bf5-45c0-9a6d-61ad659d8ba1</id> |
424 <id>c3827486-6bf5-45c0-9a6d-61ad659d8ba1</id> |
425 <text>GNU Gettext or other standard framework (like Java resource bundles) should be used</text> |
425 <text>GNU Gettext or other standard framework (like Java resource bundles) should be used</text> |
426 </item> |
426 </item> |
522 <id>f50d17bd-701f-45f9-aae4-86bfcf34cd7c</id> |
522 <id>f50d17bd-701f-45f9-aae4-86bfcf34cd7c</id> |
523 <text>discussion forum</text> |
523 <text>discussion forum</text> |
524 </item> |
524 </item> |
525 <item> |
525 <item> |
526 <id>e746eb5b-8d8b-4ec8-9315-a311f35e156a</id> |
526 <id>e746eb5b-8d8b-4ec8-9315-a311f35e156a</id> |
527 <text>do not 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</text> |
527 <text>do not 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</text> |
528 </item> |
528 </item> |
529 <item> |
529 <item> |
530 <id>a1a3c037-37e3-4283-abab-e275f7d17442</id> |
530 <id>a1a3c037-37e3-4283-abab-e275f7d17442</id> |
531 <text>Q&A tool + FAQ</text> |
531 <text>Q&A tool + FAQ</text> |
532 </item> |
532 </item> |
533 <item> |
533 <item> |
534 <id>ff537045-819e-4dec-a020-d2c9f2c3292b</id> |
534 <id>ff537045-819e-4dec-a020-d2c9f2c3292b</id> |
535 <text>there should be a second-level internet domain for the project or its team</text> |
535 <text>there should be a second-level internet domain for the project or its team</text> |
536 </item> |
536 </item> |
537 <item> |
537 <item> |
538 <id>b54d4978-974b-4743-bdba-7d4957bc9ba7</id> |
538 <id>b54d4978-974b-4743-bdba-7d4957bc9ba7</id> |
539 <text>but do not 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</text> |
539 <text>but do not 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</text> |
540 </item> |
540 </item> |
541 <item> |
541 <item> |
542 <id>a1141312-5177-4d68-bb14-fce952d542c3</id> |
542 <id>a1141312-5177-4d68-bb14-fce952d542c3</id> |
543 <text>URLs should be as stable as possible (do not break old links, set up redirections if needed)</text> |
543 <text>URLs should be as stable as possible (do not break old links, set up redirections if needed)</text> |
544 </item> |
544 </item> |
582 <id>da7dabf6-f2d8-43bc-8121-6e4527eaa691</id> |
582 <id>da7dabf6-f2d8-43bc-8121-6e4527eaa691</id> |
583 <text>to have an account on any particular third party service like particular e-mail or hosting provider</text> |
583 <text>to have an account on any particular third party service like particular e-mail or hosting provider</text> |
584 </item> |
584 </item> |
585 <item> |
585 <item> |
586 <id>dfd6a77f-7c4a-430a-8199-8ea71ec7ee8c</id> |
586 <id>dfd6a77f-7c4a-430a-8199-8ea71ec7ee8c</id> |
587 <text>to sign a contract (which includes accepting „Terms and conditions“) with any particular third party (e.g. source code hosting provider)</text> |
587 <text>to sign a contract (which includes accepting „Terms and conditions“) with any particular third party (e.g. source code hosting provider)</text> |
588 </item> |
588 </item> |
589 <item> |
589 <item> |
590 <id>af6a589f-d419-483f-b7b2-07b6e9da3924</id> |
590 <id>af6a589f-d419-483f-b7b2-07b6e9da3924</id> |
591 <text>to sign any political, religious or other proclamation or agree with it</text> |
591 <text>to sign any political, religious or other proclamation or agree with it</text> |
592 </item> |
592 </item> |
602 <id>ef9e64cc-90b0-4002-ab5a-a1135332c7fe</id> |
602 <id>ef9e64cc-90b0-4002-ab5a-a1135332c7fe</id> |
603 <text>or use similar decentralized technology which has open standard and free software implementations</text> |
603 <text>or use similar decentralized technology which has open standard and free software implementations</text> |
604 </item> |
604 </item> |
605 <item> |
605 <item> |
606 <id>d7a94eba-efd6-471f-9c32-6ee9d3b8ab29</id> |
606 <id>d7a94eba-efd6-471f-9c32-6ee9d3b8ab29</id> |
607 <text>to assign the copyright to the project and grant a free license for all patents relevant to the contribution</text> |
607 <text>to assign the copyright to the project and grant a free license for all patents relevant to the contribution</text> |
608 </item> |
608 </item> |
609 </item> |
609 </item> |
610 <item> |
610 <item> |
611 <id>e394c792-8294-4f15-a356-89cd0a7aa255</id> |
611 <id>e394c792-8294-4f15-a356-89cd0a7aa255</id> |
612 <text>the project should record all accepted contributions and maintain a public list of all authors/contributors</text> |
612 <text>the project should record all accepted contributions and maintain a public list of all authors/contributors</text> |
613 </item> |
613 </item> |
614 <item> |
614 <item> |
615 <id>b5a128a2-31d9-49df-890c-59a770f7afa9</id> |
615 <id>b5a128a2-31d9-49df-890c-59a770f7afa9</id> |
616 <text>the contributor must not loose the right to use or distribute the contributed code under any license (of his choice)</text> |
616 <text>the contributor must not loose the right to use or distribute the contributed code under any license (of his choice)</text> |
617 </item> |
617 </item> |