Last-Modified: 2023-03-25T10:59:06+00:00 SCM-Info: (git) 2023-03-25T11:00:42+00:00 - 1f2a9da1bdf4bc4a6efab252086ea3e5d7cc9ea7 SPDX-License-Identifier: CC0-1.0 SPDX-FileCopyrightText: 2023 Bruno Victal Bus factor reduction plan Multiple fronts of attack. ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– Guix ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ DOCUMENTATION =================================================== * Have a guix internals developer manual. (how 2 develop) * Guix internal API documentation. * Similar to doxygen? * Do tools for generating documentation from (Guile) Scheme source already exist? * Enforce some regularity on the texinfo markup used. [[SEE DRAFT: TEXI-CONVENTIONS]] * Makes the overall documentation consistent * Easier to contribute since the overall structure can be `copy-paste-edited` without the contributor having to be a texinfo expert. * Cycle for deprecated code removal. > Sheds weight from the guix codebase. Makes things less brittle and easier to navigate. Reduces cognitive load on the developers / maintainers. * Extend record-type* to embed documentation for fields. > Generating documentation for record-types will be made easier with this. Guix user manual --------------------------------------------------- * Include a 'HOW-DO-I-X' section. (with plenty examples) * The HTML node manual links look broken, there's information in the full version that is inacessible from the html-node counterpart. [!] Guix gotchas that should be documented ................................................... * G-Expression and Lists interaction. * Include examples. Developer manual --------------------------------------------------- Guix Internals manual. Maintainer ................................................... * PGP practices > Explain properly enough what they should do regarding PGP matters. This includes how to create, store and carry their PGP keys for guix. In short, make it so that someone who has never touched PGP can, at the end of the read, know enough to become a maintainer with commit access. * Explain the 'world rebuilding' and how to avoid it. > Explain how do maintainers know which commits (not just package ones) can induce mass rebuilding. ## TODO list (low-hanging fruit) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * Document how the following files work: * gnu/local.mk * Document how the following features work: * check * check-system Guix packages =================================================== * Enforce some consistency/guidelines on how to patch sources. > There are multiple stages where patches can be done to the package source. To avert the proliferation of N+1 styles of source sophistry, I propose the following semantics-based guidelines: * Non-diff based patches (i.e. substitute*, delete-file, etc.) * If the file to be patched is present in the source checkout, patching procedures should happen within (source (snippet ...)). * If the file to be patched is generated at configure time (i.e. not present in the source checkout), use 'modify-phases' accordingly. * TODO: Any guidelines to observe in modify-phases? * Avoid patching when possible. > Many packages substitute* when they should be using #:make-flags or #:configure-flags * Extirpate cargo-cults and mystical practices * Docbook dependent packages are an example of this (as of 2023) > Properly fixing docbook packages will allow these packages to build normally without having to resort to weird substitute* incantations. [bonus] build failures are reduced as well. * Analyze the existing packages and see if there are other "cultish" patterns like the docbook one. This most likely indicates a dependency that wasn't "properly" packaged. * Pertaining patch practices * If applicable, send the patches upstream. We don't want gnu/packages to turn into a big incomprehensible ball of source incantations. * Avoid using regex blindly. Things like XML should be handled with sxml or xslt. ![sxml notes @ guile chapter] * The broader category of this advice is "avoiding bad practices". * Document what "keyword" arguments are available to lambda* procedures used in 'modify-phases'. * Obtuse package handling. * case: nginx modules > create a build system to handle this obtuseness Guix Services =================================================== Manual for a service definition writer. Include plenty of examples and cover "general patterns" that can be easily adapted for new services. ## TODO list (low-hanging fruit) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * Harmonize the service definitions in guix. > There are services that have the same 'pattern' but wildly different definitions. This is confusing to someone who will try to use existing services as a starting point. * Deduplicate commonly used procedures. > Many services reinvent the same wheel. Some even reimplement guix functionality due to unawareness of their existence. (undocumented API problem) * Extirpate improper activation-service extension usage. > "Monkey see, Monkey do" This is a endless source of hard to diagnose troubles. Until these are wiped from guix, other service writers, who will check the existing services and use them as examples will continue to use activation-service extensions for the upcoming service patches. ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– ⋄ Guix dependencies section ⋄ Shepherd ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ * Documentation, manpages improvement. * Shell auto-completion mcron ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ Make this component intuitive enough for mere mortals to use. * Improve logging and "inspection" capabilities. * Documentation improvement. Guile (Scheme) ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ * Document sxml > The documentation for this module is extremely sparse. Highest bus factor. Expect to do extensive research for information. Expect to read both projects using sxml and the guile sxml source. Starting points: * Wikipedia __sources__ * https://okmij.org/ftp/Scheme/SXML.html * Include plenty of examples * Include equivalent examples of SXML <-> XSL,XPATH,... * Document PEG module > Comments: info pages somewhat outdated and poorly formatted but shouldn't be too hard to document how PEG works. Include examples. Maybe include a larger toy example. Describe enough theory to make this comprehensible to someone who is a (persevering) enthusiast but does not have formal training. (does not need to be exhaustive, i.e. do not write a textbook here, merely cover enough material to make a toy PEG project feasible) * Suggested candidates for educational PEG examples: * .mailmap used by git // jlich * Might not be that simple. What constitutes a valid email is **tricky** (it's a nice exercise in RFC reading though!) * Document macro/syntax work Some of the Guix internals heavily rely on macro/syntax modification. Improve the documentation here so that it's intelligible to the mere mortals. * Implement missing but interesting SRFIs. /// __interesting__ is subjective > Net improvements to both Guile and Guix. * Unload some of Guix http-fetch code into Guile? > Guix almost reimplements Guile's (web client, ...) modules. Merge them into Guile? Guix's implementation supports timeouts. * (ice-9 match) * Better examples // contributed by jgart The existing examples are way too convoluted. It should begin with simpler examples and then later on include a more elaborate one. * Document pair matching. * There's another syntax, the (= car x)(= cdr y) that's only present within the source code. Extract it and put in the manual. * S-Expression comments // from apteryx The only passing mention that implies these are supported is the listing of SRFI-62 in the manual. Doing C-s #; yields no results. ``````````````````````````````````````````````````````````````````````````````````````````` ** Guile infrastructure and project health? ** Guile has no patch/bug tracker like issues.guix. This unfortunaly results in patches/bug reports going cold. Another point of concern: What's the bus factor of this project? Regular committers here are few and patch reviews are extremely scarce. Given that Guix rests upon Guile, documenting Guile innards is of equal importance. ``````````````````````````````````````````````````````````````````````````````````````````` GNU Texinfo ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ * Is the manual good enough? /// bjc messages suggest 'no' ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– ⋄ Miscellaneous ⋄ [bonus] emacs haxor setup ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ Extend/Document a guix oriented hacking setup. Best if targeted for total emacs novices. // << the author only started to use emacs since he found it as a 'good editor for scheme code'. He uses it almost as if it were notepad.exe EES / embrace, experiment, standardise ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ Push some of the guix improvements (such as record-type*) toward SRFI standardisation. ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––– ⋄ Deferred ⋄ Objectives that shouldn't incur excessive tech-debt or have negligible impact. ### Transition plan due to texinfo phaseout? ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ Alternatives to consider: // TODO: WIP, needs to be investigated. * Docbook `````````````````````````````````````````````````````````````````````` Per wikipedia: > In February 2014, Eric S. Raymond wrote that Stallman had decided to phase out texinfo in the future after discussions with him. The replacement would be a combination of HTML and a "modern lightweight format that renders to both print and HTML".[1] [1]: https://lists.gnu.org/archive/html/groff/2014-02/msg00104.html `````````````````````````````````````````````````````````````````````` ### Apply to become a maintainer "test" / practice material? ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ Quiz/multiple choices. If not as an application tool, it can serve as a training tool. The UI is mostly irrelevant, can be web, ncurses or paper based. ### Curated 'help' page à la RHEL pages? ∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓∓ Example: https://access.redhat.com/solutions/2834231 * How would this work? > Curated snippets or answers from the ML? –––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––