Here's a v2. I've changed the structure to something close to what Julien proposed, it looks a lot better now to me! The (^) should probably be tested before the final version. I don't think the list of 'guiding principles' is worded well, probably needs more work. [something I wrote previously] >> Feel free to try to separate the things, but going previous >> discussions, many tings are important, and they appear all to be >> inseparable. Well seems like I was wrong, it splits nicely in three subsections! > I’d suggest starting with a patch against that section to address one > specific point that you think is the most pressing one. From there we > can continue the discussion. As written in another response, I don't really have an opinion on what's more pressing than another. I have written three 'points', but we don't have to discuss them all at once, maybe first 20.4.5.2? That one sounds relatively simple to me. --- [start] 20.4.5 Snippets, phases and patches. Snippets, phases and patches at times serve overlapping purposes. To decide between the three, there are a few guiding principles: * In principle, Guix only has free software; when the upstream source contains some non-free software, it has to be removed such that ‘guix build --source’ returns the "freed" source code rather than the unmodified upstream source (see: 28.4.1 Software Freedom). * The source of the package needs to correspond to what is actually built (i.e., act as the corresponding source), to fulfill our ethical and legal obligations. * It is convenient for the source derived from an origin to build on any system that the upstream package supports. * The source needs to actually work, not only on your Guix system but also for other systems; this requires some care for substitutions involving store items and other architecture-specific changes. * Sometimes, there is more than one way to do it. Let's go for the simplest one. Sometimes, which tool is the simplest, is subjective, that's fine too. To make things more concrete and to resolve conflicts between the principles, a few cases have been worked out: 20.4.5.1 Removing non-free software. Non-free software has to be removed in a snippet; the reason is that a patch or phase will not work. For a patch, the problem is that a patch removing a non-free file automatically contains the non-free file (^), and we do not want anything non-free to appear in Guix even if only in its patches. For a phase, the problem is that phases do not influence the result of ‘guix build --source’. (^) It has been noted that git patches support removing files without including the file in the patch in . If it is verified that the 'patch' utility supports such patches, this method can be used and this policy adjusted appropriately. 20.4.5.2 Removing bundled libraries. Bundled libraries should not be removed with a patch, because then the patch would contain the full bundled library, which can be large. They can be removed either in a snippet or a phase, often using the procedure 'delete-file-recursively'. There are a few benefits for snippets here: When using snippets, the bundled library does not occur in the source returned by ‘guix build --source’, so users and reviewers do not have to worry about whether the bundled library contains malware, whether it is non-free, if it contains pre-compiled binaries ... There are also less licensing concerns: if the bundled libraries are removed, it becomes less likely that the licensing conditions apply to people sharing the source returned by ‘guix build --source’, especially if the bundled library is not actually used on Guix systems. (*) As such, snippets are recommended here. (*) This is _not_ a claim that you can simply ignore the licenses of libraries when they are unbundled and replaced by Guix packages -- there are less concerns, not none. 20.4.5.3 Fixing technical issues (compilation errors, test failures, other bugs ...) Usually, a bug fix comes in the form of a patch copied from upstream or another distribution. In that case, simply adding the patch to the 'patches' field is the most convenient and usually does not cause any problems; there is no need to rewrite it as a snippet or a phase. If no ready-made patch already exists, then choosing between a patch or a snippet is a matter of convenience. However, there are two things to keep in mind: First, when the fix is not Guix-specific, it is strongly desired to upstream the fix to avoid the additional maintenance cost to Guix. As upstreams cannot accept a snippet, writing a patch can be a more efficient use of time. Secondly, if the fix of a technical issue embeds a store file name, then it has to be a phase. Otherwise, if a store file name was embedded in the source, the result of 'guix build --source' would be unusable on non-Guix systems and likely also unusable on Guix systems of another architecture.