openSUSE:How to contribute to the Printing project
About the Printing project
The Printing project is the development project in the openSUSE Build Service for packages which provide the base functionality of the printing system.
Main intent of the Printing project
The main intent of the Printing project is
- provide the newest kind of base printing software for upcoming openSUSE and SUSE Linux Enterprise versions
and at the same time with same priority
- provide the same newest base printing software also for released openSUSE and SUSE Linux Enterprise versions
as far as possible with reasonable effort.
Scope of the software packages in the Printing project
Base printing software packages are in particular
- print spooler software like CUPS,
- printing filters like cups-filters,
- printer drivers like HPLIP or Gutenprint,
- printer driver related software like Ghostscript,
- plain PPD files packages like OpenPrintingPPDs,
and other software which directly belongs to the base printing system like special backends for CUPS.
In contrast software which does not directly belong to the base printing system like user frontends (e.g. printer setup tools, printing dialog GUIs, or other printing related GUIs) or applications with a major focus on printing (e.g. LaTeX or Scribus) do usually not belong to the Printing project.
General conditions for software packages in the Printing project
Of course only really free software can be accepted in the Printing project. In particular printer driver software which is not 100% free software cannot be accepted regardless how nice it would be when this or that awkward printer model would work. We will not risk any legal issue for openSUSE and SUSE Linux Enterprise and our users and contributors when software where the legal state is not clear would be accepted.
An obvious precondition for any software is that it is by default reasonably secure. In particular for software that is run as root (e.g. a setup tool or a special CUPS backend) a security audit is usually required.
How to contribute to the Printing project
In general see Portal:Factory_contribution
In particular see openSUSE:How_to_contribute_to_Factory, therein see in particular the section "How to submit a fix to a package".
Communicate in advance
If you like to contribute major changes for a package in the Printing project or when you like to contribute a new package for the Printing project first and foremost get in contact with the maintainers of the particular package or the maintainers of the Printing project.
This avoids that you do major work on your own which might not be accepted by the package maintainers and/or by the Printing project maintainers.
The openSUSE Build Service (OBS) web pages show the maintainers of the Printing project and the maintainers of a particular package (for example https://build.opensuse.org/package/users/Printing/cups shows the maintainers of the cups package). Additionally or alternatively the RPM changelog "rpm -q --changelog package_name" shows e-mail addresses of those who had worked when (latest topmost) on an installed package.
How to contribute a bugfix or a "simple version upgrade" for a package in the Printing project
A "simple version upgrade" means that there are no major incompatible changes for this version upgrade. The simplest version upgrade is when only the Version and Source tags in the RPM spec file need to be adjusted to match the new upstream source tarball plus a descriptive RPM changelog entry so that others who do not know details about that package can understand what this version upgrade is about. A normal simple version upgrade may require some further adjustments. For example new incompatible features may need to be conditionally disabled to avoid incompatible changes for released openSUSE and SLES versions or conditionally enabled to provide new incompatible features only for openSUSE Tumbleweed. In contrast a version upgrade where backward compatibility cannot be maintained with reasonable effort is not a "simple version upgrade". When backward compatibility cannot be maintained first and foremost get in contact with the maintainers of the particular package or the maintainers of the Printing project.
Step by step what to do:
- Branch from Printing/package_name so that you get home:your_OBS_user_name:branches:Printing/package_name
- Do your changes in home:your_OBS_user_name:branches:Printing/package_name
- For each change describe the change and provide a reason why the change was done in the RPM changelog. For example describe what does not work without the change or what additional functionality is provided by the change. Such a reason could be an URL to an openSUSE bug report (e.g. boo#1234) or an URL to an upstream issue report. When there is no URL you need to explain the change and its reason in a way so that others who do not yet know about it can understand what the issue is about. For each change where external references exist (like openSUSE bug reports or upstream issues) provide URLs for all external references so that others who do not yet know about the issues can get all available details and background information.
- Verify that home:your_OBS_user_name:branches:Printing/package_name still builds successfully for all build targets where Printing/package_name builds successfully.
- Download the built RPMs from home:your_OBS_user_name:branches:Printing/package_name and install or update them on your own system by using the plain 'rpm -U' command to verify that they "just install" without any issues with plain 'rpm'.
- Verify on your system that the RPMs from home:your_OBS_user_name:branches:Printing/package_name work for you. Primarily verify that you do not notice any regression. Any tiny manual additional adaption that you need to make it work is considered to be a regression. Of course you cannot test everything. But you must verify that at least for you it "just works".
- Maintain backward compatibility (as far as possible with reasonable effort): Verify that the RPMs from home:your_OBS_user_name:branches:Printing/package_name work at least on the latest stable openSUSE release which is currently openSUSE Leap 15 (which has basically the same printing system as SLES15). This means that you must test it at least on openSUSE Leap 15 (or on SLES15) to verify backward compatibility. In general it is useless if a bugfix or a version upgrade only works on openSUSE Tumbleweed (see above for the main intent of the Printing project).
- Finally you can do the OBS submitrequest from home:your_OBS_user_name:branches:Printing/package_name to Printing/package_name.
The better your description of your change is (i.e. "what") and the easier it is to understand your explanation of the reason behind your change (i.e. "why") that you provide in the RPM changelog the more likely your change gets accepted by the maintainers of Printing/package_name. For example "Foo-driver version upgrade to 1.2.3" alone is insufficient because it tells only "what" but not "why". In contrast "Bugfix for boo#1234 (upstream issue http://www.example.org/issue4567)" could be perfectly sufficient provided at least one of the openSUSE bug report and the upstream issue report is public accessible and tells about "what" and "why".
Submit early, submit often
In general submit early and submit often (cf. Wikipedia:Release early, release often).
Do not mix up several independent separated issues in one single OBS submitrequest because a submitrequest cannot be partially accepted.
When one of several independent changes in one submitrequest is not accepted by the maintainers of Printing/package_name then the whole submitrequest must be rejected (declined).
In particular do not mix up what is actually required for a bugfix or a version upgrade with some additional general clean up adaptions or even some "optimization" changes because often those additional "by the way" changes raise questions so that they cannot be "just accepted" and in the end the whole submitrequest must be rejected (declined).
On the other hand do not split several changes that belong to each other into several submitrequests.
For example submit a package version upgrade together with all additional changes that are required to make the new version "just work" in one single submitrequest.
How to contribute a new package for the Printing project
Basically do an OBS submitrequest from home:your_OBS_user_name/new_package_name to Printing/new_package_name (cf. openSUSE:How_to_contribute_to_Factory therein the section "How to add a new package to Factory").
For new packages for the Printing project the following conditions must be fulfilled:
See the above sections
- Main intent of the Printing project
- Scope of the software packages in the Printing project
- General conditions for software packages in the Printing project
Additionally see the section "How to contribute a bugfix or a 'simple version upgrade' for a package in the Printing project" that results the following conditions:
- Describe in the Summary tag and in the description section of the RPM spec file what the new package is about. In particular describe what functionality it provides in a way so that others who do not yet know about the package can understand what it is about.
- Verify that home:your_OBS_user_name/new_package_name builds successfully for all build targets where packages in the Printing project usually build successfully.
- Download the built RPM from home:your_OBS_user_name/new_package_name and install it on your own system by using the plain 'rpm -U' command to verify that it "just installs" without any issues with plain 'rpm'.
- Verify on your system that the RPM from home:your_OBS_user_name/new_package_name works for you. Primarily verify that you do not notice any issue. Any tiny manual additional adaption that you need to make it work is considered to be an issue. Of course you cannot test everything. But you must verify that at least for you it "just works".
- Maintain backward compatibility (as far as possible with reasonable effort): Verify that the RPM from home:your_OBS_user_name/new_package_name works at least on the latest stable openSUSE release which is currently openSUSE Leap 15 (which has basically the same printing system as SLES15). This means that you must test it at least on openSUSE Leap 15 (or on SLES15) to verify backward compatibility. In general it is useless if a new package only works on openSUSE Tumbleweed (see above for the main intent of the Printing project).
Finally you can do the OBS submitrequest from home:your_OBS_user_name/new_package_name to Printing/new_package_name.
In general it is recommended to get in contact with the maintainers of the Printing project in advance. This avoids that you do major work on your own which might not be accepted by the Printing project maintainers (cf. the section "Communicate in advance").
How to test a printer driver package
Testing a printer driver software package usually requires to do various test printouts on the printer devices that are supported by that particular printer driver software package.
But in practice nobody has all those printer devices that are supported by a particular printer driver software package.
In practice one may have one or at most a few printer devices. In this case all what one can do is to do test printouts on the printer devices that one has.
But what about all the other printer devices that are supported by a particular printer driver software package?
In practice the only possible way is to test a particular printer driver software even without any connected printer devices.
The basic idea how to do that is to output the final printing data that would be normally sent to the printer device into a file.
To output the final printing data into a file one needs "FileDevice Yes" in /etc/cups/cups-files.conf since CUPS >= 1.6 and for CUPS up to 1.5.4 in /etc/cups/cupsd.conf.
Additionally one should set "LogLevel debug" in /etc/cups/cupsd.conf to get verbose (i.e. meaningful) CUPS logging and debug messages in the /var/log/cups/error_log file.
After changing /etc/cups/cupsd.conf or /etc/cups/cups-files.conf one needs to restart the cupsd.
A normal printer driver software package contains for each printer model that is supported by that particular printer driver software a model-specific PPD file that is installed in a sub-directory under /usr/share/cups/model/.
For each PPD file in the printer driver software package one has to
- set up a test queue that outputs into a file,
- do a simple test printout,
- check whether or not there is data in the output file.
This only means that "there is output" but without the actual printer devices one cannot test if that output actually makes the printers print as intended.
The following testing script does that (replace printer_driver_package with the RPM package name that contains the PPD files of the printer driver software):
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.*
(Cf. "Command-line Tools" in SDB:CUPS in a Nutshell)
Finally one should check that all filtering programs that are used for print job data processing "exited with no errors" in /var/log/cups/error_log which means that "there is no error reported" but without the actual printer devices one cannot test if that print job data processing actually results valid output.
The following command shows all reported filtering programs in /var/log/cups/error_log:
grep PID /var/log/cups/error_log
Its output for a single print job could be something like (excerpt):
[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.
To get the "exited with no errors" debug messages "LogLevel debug" in /etc/cups/cupsd.conf is needed. To clean up /var/log/cups/error_log first stop the cupsd then remove /var/log/cups/error_log and finally start the cupsd (never change CUPS' own files while cupsd is running - cf. SDB:CUPS in a Nutshell).
In case of errors or when there is no output in one of the output files you should try to diagnose the cause of the issue. See SDB:How to Report a Printing Issue for basic tests and basic operations how to diagnose the cause of a printing issue. Furthermore you should get in contact with the maintainers of the particular printer driver software package or with the maintainers of the Printing project.
Automatic printer driver testing packages
In the Printing development project there are some printer driver testing packages that implement in their RPM spec files basically what the above listed testing script does.
Currently there are the printer driver testing packages
- dymo-cups-drivers-testing
- gutenprint-testing
for the printer driver packages dymo-cups-drivers and gutenprint.
Each time when a printer driver package is changed in the Printing project its associated testing package gets automatically rebuilt which means it is tested that "there is some output" for the PPDs in the printer driver package but nothing more - without the actual printer devices it cannot be tested if that output would actually make the printers print as intended (see above).
Building the printer driver testing package fails when for one or more PPDs it fails to produce "some output" which indicates something could be wrong with the printer driver package or the printer driver testing package may need some adaptions to make the failed test succeed.
So after a changed printer driver package was accepted in the Printing development project pay attention to the subsequent build result of its associated testing package (if exists).
Version upgrades for printer driver packages
For printer driver packages a version upgrade makes sense only for those users who actually have a printer device that is not yet supported with the version that we provide in an openSUSE release or in a SUSE Linux Enterprise product.
Because printer driver packages support very many different printer models it is less than hopeless to have them tested by us in a reasonable way which means: Basically printer driver packages are not at all tested for all the different supported printer models.
Therefore a printer driver package version upgrade as a regular maintenance update that all users get more or less automatically is not possible because regressions for this or that printer model are unknown in advance.
Or in other words: When a printer driver package version works for a particular user with a particular printer model there is zero reason to enforce a version upgrade for that user by a general maintenance update.
On the other hand when a printer driver package version does not work for a particular user with a particular printer model there is zero reason for that user not to do a version upgrade and try out if the newer version may work for his particular model (provided the newer version claims that model is supported).
Therefore we try to provide the newest printer driver package versions in the Printing project for as many released openSUSE and SUSE Linux Enterprise versions as far as possible with reasonable effort (see above for the main intent of the Printing project).
In general we (i.e. openSUSE) distribute the various printer driver packages from the various upstream projects but we do not develop printer drivers so that usually we cannot do anything when a particular printer driver does not work. In particular usually we cannot reproduce issues with printer drivers. In case of issues with printer drivers see SDB:How to Report a Printing Issue for basic tests and basic operations how to diagnose the cause of an issue.