openSUSE:打印项目贡献指南
关于打印项目
打印项目 (https://build.opensuse.org/project/show/Printing) 是 openSUSE 构建服务 中用于提供打印系统基本功能的软件包的开发项目。
打印项目的主要目标
打印项目的主要目标是
- 为即将发布的 openSUSE 和 SUSE Linux Enterprise 版本提供最新的基础打印软件
同时以相同的优先级
- 为已发布的 openSUSE 和 SUSE Linux Enterprise 版本提供相同的最新基础打印软件
在合理的努力范围内。
打印项目中的软件包范围
基础打印软件软件包特别是
- 打印调度软件，如 CUPS，
- 打印过滤器，如 cups-filters，
- 打印驱动程序，如 HPLIP 或 Gutenprint，
- 与打印驱动程序相关的软件，如 Ghostscript，
- 纯 PPD 文件包，如 OpenPrintingPPDs，
以及直接属于基础打印系统的其他软件，如 CUPS 的特殊后端。
与基础打印系统不直接相关的软件，如用户前端（例如打印机设置工具、打印对话框 GUI 或其他与打印相关的 GUI）或主要关注打印的应用程序（例如 LaTeX 或 Scribus），通常不属于打印项目。
打印项目中的软件包通用条件
当然，只有真正自由的软件才能被接受到打印项目中。特别是，即使某个笨拙的打印机型号能够工作，也不能接受不 100% 自由的打印机驱动程序软件。我们不会为 openSUSE 和 SUSE Linux Enterprise 及其用户和贡献者承担任何法律风险，当接受法律状态不明确的软件时。
任何软件的一个显而易见的前提是，它默认情况下必须是安全的。特别是对于以 root 用户身份运行的软件（例如设置工具或特殊的 CUPS 后端），通常需要进行安全审计。
如何为打印项目贡献
总的来说，请参阅 Portal:Factory 贡献
特别是请参阅 openSUSE:如何贡献到 Factory，其中请参阅“如何提交对软件包的修复”部分。
提前沟通
如果您想为打印项目中的软件包贡献重大更改，或者想为打印项目贡献一个新软件包，首先与特定软件包的维护者或打印项目的维护者联系。
这可以避免您独自完成大量可能不被软件包维护者和/或打印项目维护者接受的工作。
openSUSE 构建服务 (OBS) 网页显示 打印项目的维护者 以及特定软件包的维护者（例如 https://build.opensuse.org/package/users/Printing/cups 显示cups包的维护者）。 此外，或者，RPM 变更日志“rpm -q --changelog package_name” 显示已安装软件包的最新工作者（顶部）的电子邮件地址。
如何为打印项目中的软件包贡献一个错误修复或“简单的版本升级”
“简单的版本升级”意味着该版本升级没有重大的不兼容更改。最简单的版本升级是仅当版本和SourceRPM 规范文件中的标签需要调整以匹配新的上游源代码 tarball，以及一个描述性的 RPM 变更日志条目，以便其他不了解该软件包细节的人可以理解此版本升级的内容。正常的简单版本升级可能需要进一步的调整。例如，新的不兼容功能可能需要有条件地禁用，以避免对已发布的 openSUSE 和 SLES 版本造成不兼容的更改，或者有条件地启用，以便仅为 openSUSE Tumbleweed 提供新的不兼容功能。相反，如果无法以合理的努力维持向后兼容性，则该版本升级不是“简单的版本升级”。如果无法维持向后兼容性，请首先与特定软件包的维护者或打印项目的维护者联系。
逐步操作
- 从Printing/package_name分支，以便您获得home:your_OBS_user_name:branches:Printing/package_name
- 在home:your_OBS_user_name:branches:Printing/package_name
- 中进行更改。对于每个更改，请描述更改并在 RPM 变更日志中提供进行更改的原因。例如，描述在没有更改的情况下无法正常工作的内容，或者更改提供的其他功能。这样的原因可以是 openSUSE 错误报告的 URL（例如boo#1234）或上游问题报告的 URL。如果没有 URL，则需要以其他不了解该问题的人可以理解的方式解释更改及其原因。对于每个具有外部引用的更改（例如 openSUSE 错误报告或上游问题），请提供所有外部引用的 URL，以便其他不了解这些问题的人可以获取所有可用的详细信息和背景信息。
- 验证home:your_OBS_user_name:branches:Printing/package_name仍然可以成功构建所有构建目标，其中Printing/package_name可以成功构建。
- 从home:your_OBS_user_name:branches:Printing/package_name下载构建的 RPM，并使用纯rpm -U命令在您自己的系统上安装或更新它们，以验证它们“只是安装”而没有使用纯 rpm 的任何问题。
- 验证在您的系统上home:your_OBS_user_name:branches:Printing/package_name正常工作。首先验证您没有注意到任何回归。任何您需要进行才能使其工作的微小手动额外调整都被认为是回归。当然，您无法测试所有内容。但是，您必须验证至少对您来说它“只是有效”。
- 保持向后兼容性（在合理的努力范围内）：验证来自home:your_OBS_user_name:branches:Printing/package_name在最新的稳定 openSUSE 版本上工作，该版本当前是 openSUSE Leap 15（它基本上具有与 SLES15 相同的打印系统）。这意味着您必须至少在 openSUSE Leap 15（或 SLES15）上进行测试以验证向后兼容性。通常，如果错误修复或版本升级仅在 openSUSE Tumbleweed 上有效，则没有用（请参阅打印项目的主要目标）。
- 最后，您可以从home:your_OBS_user_name:branches:Printing/package_name到Printing/package_name.
进行 OBS submitrequest。您在 RPM 变更日志中提供的更改的描述越好（即“是什么”）以及您提供的更改背后的原因的解释越容易理解（即“为什么”），您的更改被Printing/package_name的维护者接受的可能性就越大。例如，仅“Foo-driver 版本升级到 1.2.3”是不够的，因为它只说明了“是什么”，而没有说明“为什么”。相反，“修复 boo#1234（上游问题 http://www.example.org/issue4567）”可能就足够了，前提是至少 openSUSE 错误报告和上游问题报告之一是公开可访问的，并说明了“是什么”和“为什么”。
尽早提交，频繁提交
总的来说，尽早提交，频繁提交（参考 Wikipedia:Release early, release often）。
不要将几个独立的更改混合在一个 OBS submitrequest 中，因为 submitrequest 不能被部分接受。
如果 submitrequest 中的几个独立更改之一不被Printing/package_name的维护者接受，则整个 submitrequest 必须被拒绝（拒绝）。
特别是，不要将实际需要进行错误修复或版本升级的内容与一些额外的常规清理调整甚至一些“优化”更改混合在一起，因为这些额外的“顺便”更改通常会引发问题，因此无法“直接接受”，最终整个 submitrequest 必须被拒绝（拒绝）。
另一方面，不要将属于彼此的几个更改拆分为几个 submitrequest。
例如，将软件包版本升级与使新版本“正常工作”所需的所有其他更改一起提交到单个 submitrequest 中。
如何为打印项目贡献一个新软件包
基本上，从home:your_OBS_user_name/new_package_name到Printing/new_package_name进行 OBS submitrequest（参考 openSUSE:如何贡献到 Factory 其中“如何将新软件包添加到 Factory”部分）。
对于打印项目的新软件包，必须满足以下条件
请参阅上述部分
- 打印项目的主要目标
- 打印项目中的软件包范围
- 打印项目中的软件包通用条件
此外，请参阅“如何为打印项目中的软件包贡献一个错误修复或‘简单的版本升级’部分”，结果是以下条件
- 在摘要标签和在descriptionRPM 规范文件部分，描述新软件包的内容。特别是，描述它提供的功能，以便即使不了解该软件包的人也能理解它的用途。
- 验证home:your_OBS_user_name/new_package_name在通常打印项目中的软件包能够成功构建的所有构建目标上都成功构建。
- 从home:your_OBS_user_name/new_package_name下载构建的 RPM，并通过使用简单的 'rpm -U' 命令在您自己的系统上安装它，以验证它是否“正常安装”，而不会在使用纯 'rpm' 时出现任何问题。
- 验证您的系统上的 RPM 来自home:your_OBS_user_name/new_package_name是否对您有效。主要验证您是否没有注意到任何问题。您需要做的任何微小的手动额外调整都被认为是一个问题。当然，您无法测试所有内容。但是，您必须验证至少对您来说它“正常工作”。
- 保持向后兼容性（在合理努力范围内尽可能地）：验证来自home:your_OBS_user_name/new_package_name的 RPM 至少适用于最新的稳定 openSUSE 版本，当前为 openSUSE Leap 15（它基本上与 SLES15 具有相同的打印系统）。这意味着您必须至少在 openSUSE Leap 15（或 SLES15）上进行测试，以验证向后兼容性。通常，如果一个新软件包仅适用于 openSUSE Tumbleweed，则毫无用处（有关打印项目的主要意图，请参见上文）。
最后，您可以从home:your_OBS_user_name/new_package_name到Printing/new_package_name.
通常建议提前与打印项目的维护者联系。这可以避免您独自完成大量工作，而这些工作可能不被打印项目维护者接受（参阅“提前沟通”部分）。
如何测试打印机驱动程序包
测试打印机驱动程序软件包通常需要对该特定打印机驱动程序软件包支持的打印机设备进行各种测试打印。
但在实践中，没有人拥有该特定打印机驱动程序软件包支持的所有这些打印机设备。
在实践中，您可能只有一台或最多几台打印机设备。在这种情况下，您所能做的就是在您拥有的打印机设备上进行测试打印。
但是，对于该特定打印机驱动程序软件包支持的所有其他打印机设备呢？
在实践中，唯一可行的方法是在没有连接任何打印机设备的情况下测试特定的打印机驱动程序软件。
其基本思想是将通常发送到打印机设备的最终打印数据输出到文件中。
要将最终打印数据输出到文件，您需要 CUPS >= 1.6 中的 /etc/cups/cups-files.conf 中设置“FileDevice Yes”，对于 CUPS 高达 1.5.4，则在 /etc/cups/cupsd.conf 中设置。
此外，您应该在 /etc/cups/cupsd.conf 中设置“LogLevel debug”，以便在 /var/log/cups/error_log 文件中获得详细（即有意义的）CUPS 日志记录和调试消息。
更改 /etc/cups/cupsd.conf 或 /etc/cups/cups-files.conf 后，您需要重新启动 cupsd。
正常的打印机驱动程序软件包包含每个受该特定打印机驱动程序软件包支持的打印机型号的特定于型号的 PPD 文件，这些文件安装在 /usr/share/cups/model/ 下的子目录中。
对于打印机驱动程序软件包中的每个 PPD 文件，您必须
- 设置一个输出到文件的测试队列，
- 进行简单的测试打印，
- 检查输出文件中是否有数据。
这仅仅意味着“有输出”，但如果没有实际的打印机设备，您无法测试该输出是否实际上使打印机按预期打印。
以下测试脚本执行此操作（将 printer_driver_package 替换为包含打印机驱动程序的 PPD 文件的 RPM 软件包名称）
for PPD in $( rpm -ql printer_driver_package | grep -o '/usr/share/cups/model/.*\.ppd[.gz]*' ) do ppd=$( basename $PPD ) echo testing $PPD lpadmin -p testq -v file:/tmp/testprint.$ppd -P $PPD -E echo Test printout using $PPD | lp -d testq sleep 3 echo output sent to /tmp/testprint.$ppd lpadmin -x testq done ls -lhS /tmp/testprint.*
(参阅 SDB:CUPS in a Nutshell 中的“命令行工具”)
最后，您应该检查用于打印作业数据处理的所有过滤程序在 /var/log/cups/error_log 中“没有错误退出”，这意味着“没有报告错误”，但如果没有实际的打印机设备，您无法测试该打印作业数据处理是否产生有效输出。
以下命令显示 /var/log/cups/error_log 中的所有报告的过滤程序
grep PID /var/log/cups/error_log
对于单个打印作业的输出可能如下所示（摘录）
[Job 123] Started filter /usr/lib/cups/filter/texttopdf (PID 12345) [Job 123] Started filter /usr/lib/cups/filter/pdftopdf (PID 12346) [Job 123] Started filter /usr/lib/cups/filter/gstoraster (PID 12347) [Job 123] Started filter /usr/lib/cups/filter/rastertoFancyPrinter (PID 12348) [Job 123] PID 12345 (/usr/lib/cups/filter/texttopdf) exited with no errors. [Job 123] PID 12346 (/usr/lib/cups/filter/pdftopdf) exited with no errors. [Job 123] PID 12347 (/usr/lib/cups/filter/gstoraster) exited with no errors. [Job 123] PID 12348 (/usr/lib/cups/filter/rastertoFancyPrinter) exited with no errors.
要获得“没有错误退出”调试消息，需要在 /etc/cups/cupsd.conf 中设置“LogLevel debug”。要清理 /var/log/cups/error_log，首先停止 cupsd，然后删除 /var/log/cups/error_log，最后启动 cupsd（切勿在 cupsd 运行时更改 CUPS 自己的文件 - 参阅 SDB:CUPS in a Nutshell）。
如果出现错误或输出文件之一中没有输出，您应该尝试诊断问题的原因。有关基本测试和基本操作，请参阅 SDB:How to Report a Printing Issue，了解如何诊断打印问题的原因。此外，您应该与特定打印机驱动程序软件包的维护者或与打印项目维护者联系。
自动打印机驱动程序测试软件包
在打印开发项目中，有一些打印机驱动程序测试软件包，它们在 RPM 规范文件中基本上执行了上述测试脚本所做的事情。
目前有打印机驱动程序测试软件包
- dymo-cups-drivers-testing
- gutenprint-testing
用于打印机驱动程序软件包 dymo-cups-drivers 和 gutenprint。
每次在打印项目中更改打印机驱动程序软件包时，其关联的测试软件包都会自动重建，这意味着它被测试了打印机驱动程序软件包中的 PPD 是否“有一些输出”，但仅此而已 - 没有实际的打印机设备，无法测试该输出是否实际上会使打印机按预期打印（参见上文）。
如果一个或多个 PPD 无法产生“一些输出”，则构建打印机驱动程序测试软件包将失败，这表明打印机驱动程序软件包可能存在问题，或者打印机驱动程序测试软件包可能需要进行一些调整才能使失败的测试成功。
因此，在更改后的打印机驱动程序软件包被打印开发项目接受后，请注意其关联测试软件包的后续构建结果（如果存在）。
打印机驱动程序软件包的版本升级
对于打印机驱动程序软件包，只有那些尚未在 openSUSE 版本或 SUSE Linux Enterprise 产品中提供的版本中支持的打印机设备的用户，版本升级才有意义。
由于打印机驱动程序软件包支持非常多的不同打印机型号，以合理的方式对其进行测试是毫无希望的，这意味着：基本上，打印机驱动程序软件包根本没有针对所有不同的支持的打印机型号进行测试。
因此，打印机驱动程序软件包的版本升级作为常规维护更新，所有用户或多或少自动获得是不可能的，因为对于此或该打印机型号的回归是提前未知的。
或者换句话说：当打印机驱动程序软件包的版本对拥有特定打印机型号的特定用户有效时，没有理由通过常规维护更新强制该用户进行版本升级。
另一方面，当打印机驱动程序软件包的版本对拥有特定打印机型号的特定用户无效时，该用户没有理由不进行版本升级并尝试新版本是否适用于他的特定型号（前提是新版本声称支持该型号）。
因此，我们尝试在打印项目中为尽可能多的已发布 openSUSE 和 SUSE Linux Enterprise 版本提供最新的打印机驱动程序版本，在合理努力范围内（有关打印项目的主要意图，请参见上文）。
通常，我们（即 openSUSE）从各个上游项目分发各种打印机驱动程序软件包，但我们不开发打印机驱动程序，因此通常我们无法在打印机驱动程序无法工作时做任何事情。特别是，我们通常无法重现打印机驱动程序的问题。如果出现打印机驱动程序问题，请参阅 SDB:How to Report a Printing Issue，了解基本测试和基本操作，了解如何诊断问题的原因。