<?xml version="1.0" encoding="UTF-8"?>

<!--

	Sane software manifesto

	Copyright © 2019 František Kučera (Frantovo.cz, GlobalCode.info)

	This manifesto is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.

    https://creativecommons.org/licenses/by-nd/4.0/

	If distributed, official website of Sane software manifesto must be provided: https://sane-software.globalcode.info/

-->

<manifesto

	xmlns="tag:globalcode.info,2019:sane-software/manifesto"

	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

	xsi:schemaLocation="tag:globalcode.info,2019:sane-software/manifesto ../schema/ssm.xsd">

	<title>Sane software manifesto</title>

	<id>fd466b50-6abd-4294-b11f-a5b8f2f39c2a</id>

	<url>https://sane-software.globalcode.info/</url>

	<author>František Kučera (Frantovo.cz, GlobalCode.info)</author>

	<license>

		<name>Creative Commons Attribution-NoDerivatives 4.0 International License</name>

		<abbreviation>CC-BY-ND</abbreviation>

		<url>https://sane-software.globalcode.info/license/CC-BY-ND-4.0.txt</url>

		<year>2019</year>

		<prefix>This manifesto is licensed under the </prefix>

		<suffix>.</suffix>

	</license>

	<preamble>In respect to user freedoms, privacy, liberty and software quality we create software according to the following guidelines. Developing Sane software is not easy, however we believe that this is the right way because this software is written once but used many times and maintained for years or decades.</preamble>

	<chapter>

		<name>Free software</name>

		<id>ca4d0f6c-9996-49ac-8647-b7f15b049b03</id>

		<item>

			<id>a755410b-6264-4094-b339-aeca55448e8d</id>

			<type>requirement</type>

			<text>Every piece of Sane software is also Free software (as originally defined by Richard Stallman).</text>

			<text>Which means that the user has freedom to</text>

			<text>run the program for any purpose,</text>

			<text>to study and change it (i.e. has access to the source code under a free software license)</text>

			<text>and to distribute modified or unmodified copies.</text>

			<link>

				<url>https://www.gnu.org/philosophy/free-sw.html</url>

				<type>compatible</type>

				<title>What is free software? – The Free Software Definition</title>

				<quotation>“Free software” means software that respects users' freedom and community. Roughly, it means that the users have the freedom to run, copy, distribute, study, change and improve the software. Thus, “free software” is a matter of liberty, not price. To understand the concept, you should think of “free” as in “free speech,” not as in “free beer”. We sometimes call it “libre software,” borrowing the French or Spanish word for “free” as in freedom, to show we do not mean the software is gratis.</quotation>

				<quotation>A program is free software if the program's users have the four essential freedoms: The freedom to run the program as you wish, for any purpose (freedom 0). The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1). Access to the source code is a precondition for this. The freedom to redistribute copies so you can help others (freedom 2). The freedom to distribute copies of your modified versions to others (freedom 3). By doing this you can give the whole community a chance to benefit from your changes. Access to the source code is a precondition for this.</quotation>

			</link>

			<link>

				<url>https://www.gnu.org/philosophy/who-does-that-server-really-serve.html</url>

				<type>related</type>

				<title>Who does that server really serve?</title>

				<description>About Software as a Service (SaaS) and Service as a Software Substitute (SaaSS)</description>

				<quotation>On the Internet, proprietary software isn't the only way to lose your freedom. Service as a Software Substitute, or SaaSS, is another way to give someone else power over your computing.</quotation>

			</link>

		</item>

		<item>

			<id>b7cd1a50-79eb-4df2-925c-7243a46d5ed8</id>

			<type>information</type>

			<text>The user controls his computer and software and owns the data. Not the author of the software or anyone else without user's explicit consent.</text>

		</item>

		<item>

			<id>c78a9796-7862-4dd2-8ad9-3fdae094fe2c</id>

			<type>requirement</type>

			<text>Must be buildable using free software toolchain (like GNU/Linux + GCC or OpenJDK etc.).</text>

			<link>

				<url>https://www.gnu.org/prep/maintain/maintain.html#Ethical-and-Philosophical-Consideration</url>

				<type>compatible</type>

				<title>Information for Maintainers of GNU Software: Ethical and Philosophical Consideration</title>

				<quotation>A GNU package should not recommend use of any non-free program, nor should it require a non-free program (such as a non-free compiler or IDE) to build. Thus, a GNU package cannot be written in a programming language that does not have a free software implementation.</quotation>

				<quotation>Now that GNU/Linux systems are widely available, all GNU packages should provide full functionality on a 100% free GNU/Linux system, and should not require any non-free software to build or function.</quotation>

				<quotation>Similarly, a GNU package should not require the use of non-free software, including JavaScript, for the coordination of its development.</quotation>

			</link>

		</item>

		<item>

			<id>b3c0daaf-dcaf-49a8-ae38-40590456a315</id>

			<type>requirement</type>

			<text>Must not promote non-free (proprietary) software or services.</text>

			<link>

				<url>https://www.gnu.org/prep/standards/standards.html#References</url>

				<type>compatible</type>

				<title>GNU Coding Standards: References to Non-Free Software and Documentation</title>

				<quotation>A GNU program should not recommend, promote, or grant legitimacy to the use of any non-free program. Proprietary software is a social and ethical problem, and our aim is to put an end to that problem. We can’t stop some people from writing proprietary programs, or stop other people from using them, but we can and should refuse to advertise them to new potential customers, or to give the public the idea that their existence is ethical.</quotation>

			</link>

		</item>

		<item>

			<id>b2fd5d2d-4d47-48e8-8abc-4b1aa94a7951</id>

			<type>recommendation</type>

			<text>Copyleft licenses (like GNU GPL or GNU Affero GPL) are strongly 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 not benefit from the free software albeit the software is build on originally free source code.</text>

		</item>

		<item>

			<id>c3599313-338b-428d-885f-964a443d76c6</id>

			<type>requirement</type>

			<text>The license must be compatible with GNU GPLv3 in order to allow mixing with the GPL code.</text>

			<text>The only exception is older software (created before this manifesto i.e. 2019) which is unable to change the license</text>

			<text>due to the copyright owned by many authors who can not be reached anymore and who can not provide approval with the license upgrade.</text>

			<text>Such software is called „Sane with exception“.</text>

			<!-- TODO: provide exact wording of the exception e.g. XYZ is „Sane software (with GPLv2 license exception)“ -->

			<note>Software versioned under GPLv2+ or GPLv3+ is compatible with GPLv3.</note>

		</item>

		<item>

			<id>f39b90ae-0054-467e-a9e2-43379b7c2331</id>

			<type>requirement</type>

			<text>If the software is distributed with a hardware, the hardware must support installation of independently built software without any restrictions or requirements (e.g. digital signature from the original author).</text>

		</item>

	</chapter>

	<chapter>

		<name>Documented</name>

		<id>e1c828c5-0a4f-4948-9943-db1ae16a42d5</id>

		<item>

			<id>c63ea2ac-c255-4f3e-a0e2-b49d1e145347</id>

			<type>requirement</type>

			<text>At least basic documentation must be released under a free license (GNU FDL is recommended).</text>

			<link>

				<url>https://www.gnu.org/prep/standards/standards.html#License-for-Manuals</url>

				<type>compatible</type>

				<title>GNU Coding Standards: License for Manuals</title>

				<quotation>Please use the GNU Free Documentation License for all GNU manuals that are more than a few pages long.</quotation>

			</link>

		</item>

		<item>

			<id>fd8e3bbd-d46a-40fe-85a6-b902336456d4</id>

			<type>requirement</type>

			<text>Every advertised feature must be properly documented. Undocumented features can not be considered as features from the user/customer point-of-view.</text>

		</item>

		<item>

			<id>e4dede5b-059e-4e47-b03d-80142b8467f1</id>

			<type>information</type>

			<text>There might be also other documentation/books released under any license and price.</text>

			<link>

				<url>https://www.gnu.org/prep/standards/standards.html#Reading-other-Manuals</url>

				<type>related</type>

				<title>GNU Coding Standards: Reading other Manuals</title>

				<quotation>There may be non-free books or documentation files that describe the program you are documenting.</quotation>

				<quotation>It is ok to use these documents for reference, just as the author of a new algebra textbook can read other books on algebra.</quotation>

			</link>

		</item>

		<item>

			<id>c0df4d14-43f8-4b61-83c4-fb5896161aeb</id>

			<type>requirement</type>

			<text>But average software engineer must be able to build and operate the software with just the free (basic) documentation.</text>

			<link>

				<url>https://www.gnu.org/prep/standards/standards.html#Configuration</url>

				<type>related</type>

				<title>GNU Coding Standards: How Configuration Should Work</title>

				<quotation>Each GNU distribution should come with a shell script named configure.</quotation>

			</link>

		</item>

		<item>

			<id>e6cd9c52-0e66-402c-930c-901fa66acd22</id>

			<type>requirement</type>

			<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>

		</item>

		<!--

		TODO: documentation target groups and big picture:

		<item><id></id><text>documentation should focus on all target groups: users, administrators, developers</text></item>

		<item><id></id><text>there must be a big picture and software architercure described</text></item>

		-->

	</chapter>

	<chapter>

		<name>Semantic versioning and upgrades</name>

		<id>aa8bd952-842b-4391-aefe-d9b3750e432d</id>

		<item>

			<id>a8beddfc-11e3-4012-9f88-f79dc88eee16</id>

			<type>requirement</type>

			<text>Semantic versioning is required.</text>

			<text>The version number consists of three numbers: major.minor.patch.</text>

			<text>Major version is incremented if there is an incompatible change.</text>

			<text>Minor version is incremented if a feature is added in a compatible way.</text>

			<text>Patch version is incremented if a bug is fixed in a compatible way.</text>

			<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>

			<note>Propper Semantic versioning is especially important if the software is suposed to be used as dependency by others.</note>

			<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>

			<link>

				<url>http://semver.org/</url>

				<type>compatible</type>

				<title>Semantic Versioning</title>

			</link>

			<link>

				<url>https://www.gnu.org/prep/standards/standards.html#Releases</url>

				<type>compatible</type>

				<title>GNU Coding Standards: Making Releases</title>

				<quotation>You should identify each release with a pair of version numbers, a major version and a minor. We have no objection to using more than two numbers</quotation>

			</link>

		</item>

		<item>

			<id>cf557a11-b307-4c2f-a7b5-5d2485d23258</id>

			<type>requirement</type>

			<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>

		</item>

		<item>

			<id>dd013325-bf22-43d3-9579-0e272e2ac344</id>

			<type>information</type>

			<text>APIs, file formats and protocols might (and usually should) be semantically versioned independently from the implementation.</text>

			<note>In such case, there should be a table documenting which API/format/protocol version matches which implementation version.</note>

		</item>

		<item>

			<id>dacb98cc-b558-4f0e-942d-e12004e45606</id>

			<type>recommendation</type>

			<text>The branching model in the version control system should reflect the semantic versioning.</text>

			<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>

			<text>Where the v_2.3 branch was forked from the v_2 branch – from the v2.3 tag.</text>

		</item>

		<item>

			<id>ae33d206-4988-44ec-b8e2-3120019fcf2f</id>

			<type>recommendation</type>

			<text>Do not remove features unless they are really obsolete, unused or irreparably broken.</text>

		</item>

		<item>

			<id>c542336a-fce8-412c-a8dd-1328c1a884ec</id>

			<type>information</type>

			<text>The user interface might be simplified or redesigned while preserving the features under the hood.</text>

		</item>

		<item>

			<id>ba8fecf0-5c02-4fdf-abdc-2650d428f82a</id>

			<type>requirement</type>

			<text>Incompatible changes must be planned and announced in advance.</text>

		</item>

		<item>

			<id>f4826891-e732-45e8-b929-25d1182fa141</id>

			<type>requirement</type>

			<text>Upgrade scripts and upgrade documentation must be provided.</text>

		</item>

	</chapter>

	<chapter>

		<name>Interfaces, formats and protocols</name>

		<id>d34ce339-197c-44ee-9e5c-6d7e212f8c10</id>

		<item>

			<id>be4c72d1-c494-4c44-aeb4-c5847f5a3524</id>

			<type>recommendation</type>

			<text>Open standards (protocols, formats) should be used if they exist.</text>

		</item>

		<item>

			<id>b2202690-8a6c-467f-a2b1-b154f470aa77</id>

			<type>requirement</type>

			<text>Already existing open protocol/format must not be modified or extended in a way which effectively creates a proprietary protocol/format.</text>

		</item>

		<item>

			<id>dd206223-9525-4229-be2b-84b07c2b8244</id>

			<type>information</type>

			<text>New open standards (specifications) should be defined and published if needed.</text>

			<text>Such standards must be semantically versioned.</text>

		</item>

		<item>

			<id>d341b78e-15b9-4077-8b48-9e54c93391ac</id>

			<type>recommendation</type>

			<text>And they should be written in machine readable format (e.g. WSDL, ASN.1, XML Schema, Diameter dictionary, D-Bus) or at least formal language (Backus–Naur Form, EBNF etc.)</text>

		</item>

		<item>

			<id>d61b3e31-bb9f-4333-87c8-9fb32f33a49d</id>

			<type>recommendation</type>

			<text>Also configuration should have machine readable description and the user should be able to test it by executing a command (validator).</text>

		</item>

	</chapter>

	<chapter>

		<name>Modular architecture and extensibility</name>

		<id>c56e7e86-e480-4a5d-8a47-ab155dcd59b1</id>

		<item>

			<id>e50424e8-94f3-48aa-bf01-0ba984eb2349</id>

			<type>requirement</type>

			<text>Larger and multi-purpose software must be divided into smaller modules.</text>

			<link>

				<url>http://wiki.apidesign.org/wiki/NetBeans_Runtime_Container#Modularity_Manifesto</url>

				<type>compatible</type>

				<title>Modularity Manifesto</title>

				<quotation>Splitting application into modules can greatly improve the design. It is not hard to guess that a monolithic piece of code where every line in any source code can access any other source file is much more interconnected and unreadable than a code which introduces many modules and allows such uncontrolled calls to happen just inside the module.</quotation>

				<quotation>Modularity would give systems clearer design, control of dependencies between modules and give developers more flexibility in maintanence. Think about it when starting any new project - nevertheless big it is, do it in modular way. It is going to be big plus for the architecture of the whole application as it grows from its child days.</quotation>

			</link>

		</item>

		<item>

			<id>e752efae-75c9-4620-aa14-65c4949a3609</id>

			<type>requirement</type>

			<text>The modules must have defined dependencies (less = better).</text>

			<note>Dependencies needed to write an extension/module (i.e. header files, API classes/interfaces) should be as small as possible (do not require large codebase to write a mere plug-in).</note>

			<note>The required dependency should contain just interfaces (method/function signatures) and data structures but no implementation (executable code).</note>

		</item>

		<item>

			<id>e9988ed0-d686-41a0-9f1e-3243ac5235d5</id>

			<type>recommendation</type>

			<text>Particular modules should be compilable and executable (installable) independently.</text>

			<text>It should not be necessary to recompile the core and other modules if only one module is changed.</text>

			<note>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.</note>

			<note>The goal is to reduce the complexity and the code footprint that comes into the play if the user needs only certain features.</note>

		</item>

		<!--

			TODO: the package name and the version number should serve as a unique identifier for a set of features.

			If there are any build-time options/parameters, they could tune the intarnal details of the package/module, or choose some alternative dependency (like cryptography library A vs. cryptography library B),

			but the public interface and publicly provided features (the contract) should stay unchanged.

		-->

		<item>

			<id>a7bc51ba-9832-4f75-983c-e75dc0801113</id>

			<type>information</type>

			<text>Another good ways to extend and customize the software are:</text>

			<text>configuration (XML, INI, RegExp, SQL, XSLT, XPath etc.) and</text>

			<text>scripting (Scheme, Bash, Python, Lua, ECMA Script etc.)</text>

			<link>

				<url>https://www.gnu.org/prep/standards/standards.html#Source-Language</url>

				<type>compatible</type>

				<title>GNU Coding Standards: Which Languages to Use</title>

				<quotation>The more GNU components use Guile and Scheme, the more users are able to extend and combine them</quotation>

				<quotation>Many programs are designed to be extensible: they include an interpreter for a language that is higher level than C. Often much of the program is written in that language, too. The Emacs editor pioneered this technique.</quotation>

				<quotation>The standard extensibility interpreter for GNU software is Guile, which implements the language Scheme (an especially clean and simple dialect of Lisp).</quotation>

			</link>

			<link>

				<url>https://www.gnu.org/software/guile/</url>

				<type>related</type>

				<title>GNU Guile</title>

				<description>GNU implementation of the Scheme language (which is a dialect of Lisp).</description>

			</link>

		</item>

	</chapter>

	<chapter>

		<name>Testable</name>

		<id>a0376231-d53e-45fd-826f-47148721de3d</id>

		<item>

			<id>d99a69a5-2572-4517-a775-b69d036ad79c</id>

			<type>information</type>

			<text>Tests verify the compliance of the implementation with the documentation or specification.</text>

		</item>

		<!-- TODO: the software should be structured in a way which facilitates writing tests – e.g. separate the UI from the core and allow calling the core functions from the tests – which has also other positive side effects  -->

		<item>

			<id>d95dc118-7473-4f18-8b9e-35830a87b269</id>

			<type>recommendation</type>

			<text>There should be automated build-time complex tests for the package. The test feeds the program with sample input and verifies expected output.</text>

		</item>

		<item>

			<id>a9f6725d-ddf1-41ee-96b4-15f3b851cb50</id>

			<type>recommendation</type>

			<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>

		</item>

		<item>

			<id>d610c04b-cc44-48c7-b069-f41b90bdef0f</id>

			<type>recommendation</type>

			<text>Unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces.</text>

		</item>

		<item>

			<id>e85baeda-8fcb-42d1-bb53-d7386a941ae7</id>

			<type>recommendation</type>

			<text>Each external interface should contain procedure/function that does nothing important or heavy, is idempotent and returns simple response which proves that the interface (connection) is working (e.g. echo, print version, status or current time). If authentication and authorization mechanisms are present, there should be one procedure/function callable anonymously and one that requires authorization.</text>

		</item>

	</chapter>

	<chapter>

		<name>Safe code and sustainability</name>

		<id>f3afbaf2-0933-43d2-aed0-8dc568b9429f</id>

		<item>

			<id>a96206c9-3e69-483d-b575-6bab9dec4a30</id>

			<type>requirement</type>

			<text>Correctness, safety and readability is preferred to performance.</text>

		</item>

		<item>

			<id>d8eba0dd-4305-44b9-80ea-4c38b6dfa633</id>

			<type>recommendation</type>

			<text>Strong data typing should be used, preconditions and possible exceptions should be declared in the interface and they are part of the contract.</text>

		</item>

		<item>

			<id>ebea0c16-f820-444d-a73c-3054ca6a38c8</id>

			<type>requirement</type>

			<text>Data structures must be known and well documented. Do not use e.g. undocumented map keys or properties.</text>

		</item>

		<item>

			<id>e24e600e-6542-4664-8cf0-2d8c6feb6c13</id>

			<type>recommendation</type>

			<text>Code, comments and specification should be written in the same natural language.</text>

			<link>

				<url>https://www.gnu.org/prep/standards/standards.html#Comments</url>

				<type>related</type>

				<title>GNU Coding Standards: Commenting Your Work</title>

				<quotation>Please write the comments in a GNU program in English, because English is the one language that nearly all programmers in all countries can read.</quotation>

			</link>

		</item>

		<item>

			<id>fa92aa33-a69f-43b8-9051-9bfdcd3d293f</id>

			<type>recommendation</type>

			<text>There should be a dictionary of used terms, so whole team and also users and customers will speak the same language.</text>

		</item>

		<item>

			<id>b9345a0e-c672-45d3-b93b-8d0fb4ece8b3</id>

			<type>recommendation</type>

			<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>

			<note>Avoid silent failures: e.g. if the computer runs out of disk space and the text editor is unable to save the file, it should immediately report error and allow user to choose different destination instead of silently failing and leaving the file empty.</note>

		</item>

	</chapter>

	<chapter>

		<name>Small code footprint</name>

		<id>ba8fbf3a-9254-4dd8-bb77-b0cd4907c6aa</id>

		<item>

			<id>f5389468-2f8a-43c8-884a-8df6bc844453</id>

			<type>recommendation</type>

			<text>Less LOC (or cyclomatic complexity) = better.</text>

			<note>Cyclomatic complexity is much better measure of the complexity than LOC (lines of code). But usually it is much easier to simply count lines and we can use it as a approximation.</note>

		</item>

		<item>

			<id>b6b6c838-be6d-43d5-9f99-2098fa217c54</id>

			<type>recommendation</type>

			<text>Boilerplate and unused code should be reduced. Adequately high-level programming language or framework should be used.</text>

		</item>

		<item>

			<id>b07fe0f0-2be7-4c1c-9b19-b671269c5e58</id>

			<type>recommendation</type>

			<text>Code generators should be used (during the build process, not to generate code to be manually edited and versioned).</text>

			<link>

				<url>https://www.gnu.org/prep/standards/standards.html#Releases</url>

				<type>compatible</type>

				<title>GNU Coding Standards: Making Releases</title>

				<quotation>Building and installing the program should never modify any of the files contained in the distribution. This means that all the files that form part of the program in any way must be classified into source files and non-source files. Source files are written by humans and never changed automatically; non-source files are produced from source files by programs under the control of the Makefile.</quotation>

			</link>

		</item>

	</chapter>

	<chapter>

		<name>Sane dependencies</name>

		<id>afd8f6c7-8dac-4a83-a101-64f017ec7ada</id>

		<item>

			<id>c2d5a677-a721-40e3-b560-73afe76fe2b0</id>

			<type>recommendation</type>

			<text>Avoid NIH syndrome and reuse code but also avoid dependency hell.</text>

			<text>Complexity is defined by the complexity of the program itself + complexity of its dependencies.</text>

		</item>

		<item>

			<id>d214987c-881c-450b-8544-82141866f541</id>

			<type>requirement</type>

			<text>Know your dependencies, know why they are required.</text>