From f256512ee0768a9b5ea9f45c4528161310972b65 Mon Sep 17 00:00:00 2001 From: bill-auger Date: Thu, 12 Mar 2020 06:02:40 -0400 Subject: update docs --- README | 80 +++++++++++++++++++++++++++++++----------------------------- SYNTAX | 88 +++++++++++++++++++++++++++++++++++++++++------------------------- 2 files changed, 97 insertions(+), 71 deletions(-) diff --git a/README b/README index aa60b51..358868f 100644 --- a/README +++ b/README @@ -1,40 +1,44 @@ # How to Blacklist a package (adapted from [1]Parabola GNU/Linux-Libre Wiki) -if you find a package that contains, uses or recommends nonfree +If you find a package that contains, uses or recommends nonfree software, it should be added to blacklist.txt until a way to free it -is found. more generally, any package in violation to the [2]FSDG -belongs in blacklist.txt - -other packages should be added to your-privacy-blacklist.txt, -your-freedom_emu-blacklist.txt or both if they endanger privacy or -only exist for the sake of using nonfree software; respectively. see -[3] and [4] for more info. - -## Preferred method (blacklisting the package) - - * if you don't have [5]git access: - * ask for it, or - * send a patch produced using `git format-patch` to dev@lists.parabola.nu - * if you do: - 1. if possible, start by making a [6]replacement available for all - the affected architectures (packages in - your-freedom_emu-blacklist.txt are not meant to have a - replacement), or [7]report a bug if the package could be - changed to be free (read next section) - 2. pull [8]blacklist.git - 3. add package according to the SYNTAX file - 4. push changes - 5. ssh into repo.parabola.nu and run db-check-nonfree - 6. pull [9]abslibre.git and make a new release of the - corresponding blacklist package (e.g. your-freedom) - -## Alternative method (reporting an issue) - - * file a bug report on the [3]Parabola Issue Tracker - * choose the project responsible for it, nearly always "Packages" - * choose the "Freedom issue" type and priority - * report separate issues for appropriate projects if the package is - included with installation media. +is found. More generally, any package in violation to the [2]FSDG +belongs in blacklist.txt. + +Other packages should be added to your-privacy-blacklist.txt, if they +endanger privacy, or to your-freedom_emu-blacklist.txt, if they +exist only for the purpose of emulating non-free hardware, +for running other non-free software. See [3] and [4] for more info. + +## Reporting a freedom issue + + 1. Open a bug report on the [5]Parabola Issue Tracker + 2. Choose the project responsible for it (usually "Packages") + 3. Choose the "Freedom issue" issue concern and priority + 4. Include as much detail as possible, as to why the package has freedom issues. + +## Blacklisting a package + + 1. If there is not an existing entry on the [6]LOSTDNRTFSDG wiki, or some other + detailed report which describes the known freedom issues with the package, + open a bug report on the [5]Parabola Issue Tracker as described in the + previous section, if there is not one already. Even if there is some external + bug report to reference, a Parabola ticket is preferred. This will serve as a + discussion thread and reference for the future regarding the package. + 2. If possible, start by making a useable liberated [7]replacement package + (packages in your-freedom_emu-blacklist.txt are not meant to have a replacement). + The end result should be a new PKGBUILD in [8]abslibre, and a newly released + replacement package in the repos (usually [libre]). + 3. If patching is infeasible, try to find some other program that accomplishes + the same task. There may already be suitable alternative programs in the repos. + 4. If no suitable replacement can be made or found, the last resort is to blacklist + the package without a replacement. + 5. Clone or pull the latest [9]blacklist.git + 6. Add an entry for the package according to the SYNTAX file. + 7. Run the ./validate script. + 8. Commit and push changes to the server - autobuilder will do the rest. + 9. if the push is rejected, you probably forgot step #7 + ## References: @@ -42,8 +46,8 @@ only exist for the sake of using nonfree software; respectively. see [2]: https://www.gnu.org/distros/free-system-distribution-guidelines.html [3]: https://wiki.parabola.nu/Nonprism [4]: https://wiki.parabola.nu/Emulator_licensing_issues -[5]: https://git.parabola.nu -[6]: https://wiki.parabola.nu/Creating_-libre_packages -[7]: https://labs.parabola.nu -[8]: https://git.parabola.nu/blacklist.git +[5]: https://labs.parabola.nu +[6]: http://libreplanet.org/wiki/List_of_software_that_does_not_respect_the_Free_System_Distribution_Guidelines# +[7]: https://wiki.parabola.nu/Creating_-libre_packages [9]: https://git.parabola.nu/abslibre.git +[8]: https://git.parabola.nu/blacklist.git diff --git a/SYNTAX b/SYNTAX index d86c85c..9fccebc 100644 --- a/SYNTAX +++ b/SYNTAX @@ -1,76 +1,98 @@ The *blacklist.txt files consist of lines in the following format: - original-package:[libre-replacement]:[ref]:[id]:short-description + original-package![libre-replacement]![ref]![ref-id]!reason-tag!short-description -where something within [] is optional. +where field values within [] are optional. + + +Fields Semantics: * 'original-package' is the name of the binary package from Arch + * 'libre-replacement' is the name of the binary package that provides - and replaces the original-package, or empty if there is no + and replaces the 'original-package', or empty if there is no compatible replacement. The replacement must be compatible for use by humans and scripts, e.g. fastjar is not a replacement for zip although both solve the same problem. Packages in your-freedom_emu-blacklist.txt are not meant to have a replacement. + * 'ref' is one of the keys in the first column in following table: debian : http://bugs.debian.org/ - fsf : http://libreplanet.org/wiki/List_of_software_that_does_not_respect_the_Free_System_Distribution_Guidelines# - savannah : https://savannah.nongnu.org/bugs/? fedora : https://bugzilla.redhat.com/show_bug.cgi?id= + fsf : http://libreplanet.org/wiki/List_of_software_that_does_not_respect_the_Free_System_Distribution_Guidelines# parabola : https://labs.parabola.nu/issues/ + savannah : https://savannah.nongnu.org/bugs/? The URL in the second column in above table, when concatenated with - the value of the 'id' field should form a valid URL pointing to an issue + the value of the 'ref-id' field should form a valid URL pointing to an issue reporting/describing the reason for the package being blacklisted. We should prefer FSF refs, since they are easily available for other distros. Hopefully some lines will move from parabola:X to fsf:Y with the LibrePlanet wiki linking to the X issue on labs.parabola.nu. -* 'id' refers to a reported bug on the tracker indicated in the 'ref' column + NOTE: An empty 'ref' field is deprecated, and should become an error eventually. + + +* 'ref-id' refers to a reported bug on the tracker indicated in the 'ref' column The URL in the second column in 'ref' table, when concatenated with - the value of this 'id' field should form a valid URL pointing to an issue + the value of this 'ref-id' field should form a valid URL pointing to an issue reporting/describing the reason for the package being blacklisted. -* 'short-description' categorizes original-package with some tags, - followed by a short verbal explanation. Popular tags are: + NOTE: An empty 'ref-id' field is deprecated, and should become an error eventually. + + +* 'reason-tag' broadly categorizes the reason why the 'original-package' is blacklisted. + The primary use for these, is to identify issues that are relevant to all FSDG distros, + and may deserve discussion on the gnu-linux-libre mailing list. Other tags indicate + subtle problems introduced by Arch (e.g. not including required license text, adding + an avoidable dependency on a non-free package), or just branding or technical issues + which are peculiar to Parabola (e.g. carrying a custom pacman). + The acceptable reason tags are: - [nonfree]·······This package is blatently non-free software. + [nonfree]·······This package is completely non-free software; and can not be + liberated due to licensing, or lack of source code. - [semifree]······This package is mostly free, but contains some non-free - software or documentation. + [semifree]······This package is mostly free, but contains some non-free software, + fonts, artwork, or documentation; and is a candidate for a + liberation recipe. - [uses-nonfree]··This package depends on, recommends, or otherwise - inappropriately integrates with other non-free software - or services. + [uses-nonfree]··This package requires, recommends, or otherwise integrates, indexes, + or actively assists with downloading other non-free software. - [branding]······This package has branding needs adjusted; it refers to - "Arch" instead of "Parabola", or "Linux" instead of - "GNU/Linux", etc. + [branding]······This package has branding items which needs adjusted for some reason + (e.g. it refers to "Arch" instead of "Parabola" in ways that could be + inappropriate for a derivative to present as it's own, refers to the + "Linux" operating system rather than "GNU/Linux", or has conditions + on the use of it's trademarks; which parabola can not meet). [technical]·····This package cannot be imported from Arch because of - technical reasons, rather than freedom reasons; this is - NOT to do with freedom of privacy issues in the + technical reasons, rather than freedom reasons; but + NOT related to freedom of privacy issues in the package. This usually comes down to two things: it must be recompiled against our version of a dependency package, or it must be compiled from source, as we are stricter about that than Arch is. - If this tag is present, then either the libre-replacement - column should match the the original-package column; - or the [FIXME:package] tag should also be present and - the libre-replacement column should be empty. + If this tag is present, then the 'libre-replacement' + column should always match the 'original-package' column. - [FIXME:package] This package has a free replacement, or could be built + [FIXME-package] This package has a free replacement, or could be built in a way that is acceptable, but no one has done so yet. + NOTE: This tag is deprecated. + All entries should have a libre replacement, if possible. + + [FIXME-description] Someone needs to provide a brief descriptive text. + NOTE: This tag is deprecated. + All entries should have a short-description. + + NOTE: An empty 'reason-tag' field is deprecated, and should become an error eventually. + - [FIXME:description] Someone needs to fix the description in blacklist.txt +* 'short-description' breifly explains why the package is blacklisted. - To make reporting issues to gnu-linux-libre easier, we should explain - in the description if the package is blacklisted due to an upstream FSDG - issue, problem introduced by Arch (e.g. not including required license - text, adding optional dependency on a non-free package), or just - branding, dependency or non-freedom-related issues which don't need - reporting to other distros. + NOTE: An empty 'short-description' field is deprecated, + and should become an error eventually. -- cgit v1.2.2