# HG changeset patch # User František Kučera # Date 1570392767 -7200 # Node ID fe39d69408219947c913efd63f7cce47d3dc3ea8 # Parent 9f5de01bfd304eb34b3f044934526e4c17035a14 clean-up and update of chapters: Testable Safe code and sustainability Small code footprint Sane dependencies Easily auditable Reproducible builds Trustworthy packages and sources diff -r 9f5de01bfd30 -r fe39d6940821 text/ssm.en.xml --- a/text/ssm.en.xml Sun Oct 06 09:28:14 2019 +0200 +++ b/text/ssm.en.xml Sun Oct 06 22:12:47 2019 +0200 @@ -311,25 +311,26 @@ information Tests verify the compliance of the implementation with the documentation or specification. + d95dc118-7473-4f18-8b9e-35830a87b269 recommendation - there should be automated build-time complex tests for the package – feed the program with sample input and verify expected output + There should be automated build-time complex tests for the package. The test feeds the program with sample input and verifies expected output. a9f6725d-ddf1-41ee-96b4-15f3b851cb50 recommendation - 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 + 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. d610c04b-cc44-48c7-b069-f41b90bdef0f recommendation - unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces + Unit tests are recommended for code parts that are internally complex (algorithms, important business logic) and have simple interfaces. e85baeda-8fcb-42d1-bb53-d7386a941ae7 recommendation - 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 + 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. @@ -339,22 +340,22 @@ a96206c9-3e69-483d-b575-6bab9dec4a30 requirement - correctness, safety and readability is preferred to performance + Correctness, safety and readability is preferred to performance. d8eba0dd-4305-44b9-80ea-4c38b6dfa633 recommendation - use strong data typing, declare preconditions and possible exceptions + Strong data typing should be used, preconditions and possible exceptions should be declared in the interface and they are part of the contract. ebea0c16-f820-444d-a73c-3054ca6a38c8 requirement - data structures must be known and well documented – do not use undocumented map keys or properties + Data structures must be known and well documented. Do not use e.g. undocumented map keys or properties. e24e600e-6542-4664-8cf0-2d8c6feb6c13 recommendation - code, comments and specification should be written in the same natural language + Code, comments and specification should be written in the same natural language. https://www.gnu.org/prep/standards/standards.html#Comments related @@ -365,12 +366,12 @@ fa92aa33-a69f-43b8-9051-9bfdcd3d293f recommendation - there should be a dictionary of used terms, so whole team and also users and customers will speak the same language + There should be a dictionary of used terms, so whole team and also users and customers will speak the same language. b9345a0e-c672-45d3-b93b-8d0fb4ece8b3 recommendation - 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 + 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. @@ -380,17 +381,17 @@ f5389468-2f8a-43c8-884a-8df6bc844453 recommendation - less LOC (resp. cyclomatic complexity) = better + Less LOC (resp. cyclomatic complexity) = better. b6b6c838-be6d-43d5-9f99-2098fa217c54 recommendation - reduce boilerplate and unused code + Boilerplate and unused code should be reduced. Adequately high-level programming language or framework should be used. b07fe0f0-2be7-4c1c-9b19-b671269c5e58 recommendation - use code generators (during build process, not to generate code to be manually edited and versioned) + Code generators should be used (during the build process, not to generate code to be manually edited and versioned). https://www.gnu.org/prep/standards/standards.html#Releases compatible @@ -406,52 +407,48 @@ c2d5a677-a721-40e3-b560-73afe76fe2b0 recommendation - avoid NIH and reuse code but also avoid dependency hell + Avoid NIH syndrome and reuse code but also avoid dependency hell. + Complexity is defined by the complexity of the program itself + complexity of its dependencies. d214987c-881c-450b-8544-82141866f541 requirement - know your dependencies, know why they are required - - - c8402612-e136-43b5-9209-f9800d2e94da - recommendation - reduce dependencies to only necessary ones + Know your dependencies, know why they are required. cbeb9a6b-7b64-4452-8caf-246c082a853d recommendation - depend on small and useful libraries – not on bulky application packages or libraries with large transitive dependencies + Depend on small and useful libraries – not on bulky application packages or libraries with large transitive dependencies. cbaf55be-8ffb-4109-9c83-083d1b3e793a requirement - 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 + 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. d7655989-a5e4-4123-9147-3782fc05a5ee recommendation - helper tools: + Complexity caused by helper tools should be also reduced: a5307bc9-36ed-4d83-963a-30c5c67613aa recommendation - if you e.g. use Bash and Perl during the build process, do not add also Python dependency, write it in Perl – or use Python instead of Perl. + If you e.g. use Bash and Perl during the build process, do not add also Python dependency, write it in Perl – or use Python instead of Perl. b0237d84-7068-4b2b-bc28-ce5e0a0061e4 recommendation - Or if you use Java as your main language, consider not using Python/Perl for scripting and use Java for it + Or if you use Java as your main language, consider not using Python/Perl for scripting and use some JVM language for it. a0f42ec9-5032-4f6d-a50a-4b7bddde77f0 requirement - if possible, always depend on abstract interfaces, not on particular implementations + If possible, always depend on abstract interfaces, not on particular implementations. c5974dcd-4855-40c5-ad22-894c128ca1dc recommendation - from the whole system point-of-view, Bootstrappable builds should be taken into account + From the whole system point-of-view, Bootstrappable builds should be taken into account. http://bootstrappable.org/ related @@ -466,18 +463,18 @@ aeef6a5c-bafc-4fcf-9b21-5829e8a44c5e recommendation - small code footprint and minimal dependencies makes it easy to do security audit + Small code footprint and sane dependencies make it easier to do security audit. ab69d352-da68-40c2-a3e1-a8fd5c41ad0a recommendation - avoid ungrounded refactoring and reformatting – they make mess and noise in the version control system and impede the audit + Ungrounded refactoring and reformatting should be avoided – they make mess and noise in the version control system and impede the audit. This rule is classified as a recommendation only because of the fact that past mistakes usually can not be reverted, which would disqualify the software forever. However it should be normally considered to be a requirement. e4db77b8-f145-4e43-bf8b-eb775b9352c8 - information - refactoring/reformatting changesets should be separated from substantive changes + recommendation + Refactoring/reformatting changesets should be separated from substantive changes. @@ -487,12 +484,12 @@ e5154815-eeae-4664-8883-a29a64eea325 recommendation - builds should be reproducible: same code/version → same binary package + Builds should be reproducible i.e. same code/version should lead to the same binary package. a3b0c164-4dde-4e33-b3be-5478d2a187e2 requirement - if not, it should be documented, why and how build products might differ, and there should be plan/task to make it reproducible + If they are not reproducible, it should be documented, why and how build products might differ, and there should be plan/task to make builds reproducible. @@ -502,32 +499,33 @@ a0d9322c-7d2b-4632-b543-7e0d75bb5f0b requirement - every released version (binary or source) must be cryptographically signed by the authors (GnuPG/OpenPGP is strongly recommended) + Every released version (binary or source) must be cryptographically signed by the authors (GnuPG/OpenPGP is strongly recommended). feb97ec0-c35c-49b8-b455-517a929b4a84 recommendation - there should be also checksums/hashes for every released package + There should be also checksums/hashes for every released package. ff33e209-0460-4a43-997f-d6b32b73997b recommendation - if HTTP is supported, HTTPS should also be – the attacker/eavesdropper should not even know what software/package/update is downloaded by the user + If HTTP is supported, HTTPS should also be – the attacker/eavesdropper should not even know what software/package/update is downloaded by the user. c1f83b3a-e564-4483-91de-9c08723efd13 - recommendation - 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 + requirement + The attacker must not be able to suppress updates – the program (usually a package management system) must not be silent in such case and must warn the user that something possibly nasty and dangerous is happening. + This is relevant mostly to distributions and package managers which should be used for updates (the application should not update itself). c6a755c9-a54e-4ffb-8f70-bfbd851b93c5 recommendation - releases should be downloadable also (or exclusively) over BitTorrent or other P2P network + Releases should be downloadable also (or exclusively) over BitTorrent or other P2P network. f9275c3c-2b09-4aec-ac28-76ff827d52ce requirement - source code repository must be accessible through an encrypted connection + Source code repository must be accessible through a secure and encrypted connection.