Instructions for Contributors

We are grateful for any contribution to the database and to the Foomatic software.

To organize these changes so that we know which code is for what, to back out modifications in case of regressions, ... we use a version control system which keeps track of the history of all changes done. At the Linux Foundation Bazaar is used as the version control system. So please do not send modified source tarballs to us, always generate patches with Bazaar (so-called bundles), as shown in the section "How to do changes on the Bazaar repositories".

If you only want to add one or two new printers you can also use our add printer form, but for addition of very many printers or if you also want to modify driver and option data, do your changes with Bazaar.

How to get write access to the Bazaar repositories

If you are contributing regularly, especially if you work for a printer manufacturer or for a free software printer driver project, you can ask us for write access to the Bazaar repositories. Before doing so you need to set up an account in the single sign-on system of the Linux Foundation. Simply click the appropriate link in the upper right corner of this page and fill in the form (if you have already an account, log in to check whether it is still OK). Then send an e-mail to licquia (at) debian.org and david (at) linux-foundation.org containing the user name you have chosen. Send e-mail to the same people if there are any problems when creating the account. But please do not report bugs in Foomatic, PPDs or printer drivers by e-mail, use the bug tracking system instead (product: OpenPrinting).

If you want to change your password later on, log into the MediaWiki by clicking the link in the upper right corner. Click on "preferences" near the upper right corner and you can configure your account.

If you want to post on the forums, too, use the same user name and password, you are automatically registered there.

How to do changes on the Bazaar repositories

1. Download the repositories you want to work on anonymously:

bzr branch http://bzr.openprinting.org/foomatic/foomatic-filters
bzr branch http://bzr.openprinting.org/foomatic/foomatic-db-engine
bzr branch http://bzr.openprinting.org/foomatic/foomatic-db
bzr branch http://bzr.openprinting.org/foomatic/foomatic-db-nonfree

bzr branch http://bzr.openprinting.org/foomatic-4.0/foomatic-filters
bzr branch http://bzr.openprinting.org/foomatic-4.0/foomatic-db-engine
bzr branch http://bzr.openprinting.org/foomatic-3.0/foomatic-filters
bzr branch http://bzr.openprinting.org/foomatic-3.0/foomatic-db-engine

If you download all repositories, execute the "bzr branch" commands in
the same directory, as then you will be able to test the whole system in
place, without installing.

Use the repositories of the stable line for bug fixes and small changes, and the development line for new database entries and bigger changes in the software.

2. To get your personal copies of the repositories up-to-date, execute

bzr pull

in their base directories.

3. Edit, add, or remove files in your personal copies of the repository,
document your changes in the appropriate ChangeLog file.

4. If you have added a file, register it for version control with

bzr add <file>

and if you have removed a file, unregister it with

bzr remove <file>

5. Rename or move a file under version control with

bzr mv <old> <new>

6. (Optional) Get an overview of your changes:

bzr status
bzr diff

7. Commit your changes into your personal copy of the repository:

bzr commit

8. (Optional) If you see that there is still anything else to change, you can
repeat steps 3-7 as often as you want.

9. Re-sync with the original repository

bzr merge
bzr commit

10. Generate a bundle file (this is a diff with all meta information
about the change history):

bzr bundle > mychanges.bundle

11. (Optional) For a quicker upload and also to fulfill the 8 MB upload limit,
compress your bundle:

gzip mychanges.bundle

12. If you do not have write access to our Bazaar repositories, post the
file resulting from step 10 or 11 on our forums or put it into your web space and
post a link to it. Please include also a description of your changes in your posting. Steps 13 and 14 are not relevant for you then.

13. Go to

http://bzr.openprinting.org/

click through the directories to get to the repository into which you want to submit. Then click the "PQM" link at the bottom. Enter your user name and password into the pop-up dialog. User name and password should be the old ones from openprinting.org. If I (or someone else from the Linux Foundation) have asked you to create a MediaWiki account at the Linux Foundation, use user name and password of the MediaWiki account. Now a mask with four input fields appears. Enter your e-mail address into the first, a comment about your changes into the second field, and leave the third field blank. Enter the path to your bundle (uncompressed or gzip-compressed) into the forth field, or use the "Browse" button to select the bundle file. Submit the data and in a few minutes you get an e-mail that your changes are applied (or an error mail telling that you did something wrong). If all worked fine, you can browse the web interface of the repository

http://bzr.openprinting.org/

to verify the presence of your changes.

14. (Optional) The old method of merging published branches into the official
branch is still available, but we cannot supply the needed web space to
you. If you want to use this method and have your own web space, proceed
as follows (instead of steps 9-13):

To upload the changes, copy your repository onto your web server

scp -r <repository> <user>@<server>:<path>

Once copied you can update your copy

bzr push sftp://<user>@server>/<path>

Then proceed as in step 12, but in the web form, fill the URL of your
published branch into the third field and leave the forth field blank.

The recommended method is the bundle method of steps 9-13, as much less
data has to be transported through the internet and no web space is needed.

The old method does not need Bazaar 0.9.0, it works also with 0.8.2.

15. (optional) If you have SSH access to our servers (at least to bzr.linux-foundation.org), you can use a simpler way to upload your changes instead of following steps 9-13 or 14. Do the "bzr push" command appropriate to the package to which you want to commit:

bzr push --remember bzr+ssh://<user>@bzr.linuxfoundation.org/srv/www/bzr/openprinting/foomatic/foomatic-filters
bzr push --remember bzr+ssh://<user>@bzr.linuxfoundation.org/srv/www/bzr/openprinting/foomatic/foomatic-db-engine
bzr push --remember bzr+ssh://<user>@bzr.linuxfoundation.org/srv/www/bzr/openprinting/foomatic/foomatic-db
bzr push --remember bzr+ssh://<user>@bzr.linuxfoundation.org/srv/www/bzr/openprinting/foomatic/foomatic-db-nonfree

bzr push --remember bzr+ssh://<user>@bzr.linuxfoundation.org/srv/www/bzr/openprinting/foomatic-4.0/foomatic-filters
bzr push --remember bzr+ssh://<user>@bzr.linuxfoundation.org/srv/www/bzr/openprinting/foomatic-4.0/foomatic-db-engine
bzr push --remember bzr+ssh://<user>@bzr.linuxfoundation.org/srv/www/bzr/openprinting/foomatic-3.0/foomatic-filters
bzr push --remember bzr+ssh://<user>@bzr.linuxfoundation.org/srv/www/bzr/openprinting/foomatic-3.0/foomatic-db-engine

"<user>" has to be replaced by your Linux Foundation user name. The "--remember" makes bzr saving the long upload path. So you need only to enter

bzr push

for future commits to our repositories.

The changes arrive immediately. So you can check on the web interface

http://bzr.openprinting.org/

immediately after the "bzr push".

16. (Optional) For more info about using Bazaar, go to section "Learn" of
the Bazaar web site.

Specifications for foomatic-db XML Data

When submitting XML data to foomatic-db, ensure that the data follows the guidelines detailed below.

Basic Guidelines

• All XML data must pass through

  xmllint -noout

  without any errors

foomatic-db/db/source/printer

• Naming convention

• The file name must start with the manufacturer, a dash, and then the model name with underscores for spacing.

HP-PhotoSmart_2600.xml
Epson-Stylus_CX7700.xml

XML Layout

• The <printer> tag requires the id of the printer, which is printer/Make-Model:

<printer id="printer/HP-LaserJet_4000">

• The <make> and <model> tags must be filled in with the appropriate make and model respectively

<make>HP</make>
<model>LaserJet 4000</model>

• The <mechanism> tag is a container for various mechanical tags.
  • If the printer is color, use the tag <color/>. Otherwise, insert

    <!--not "color"-->

  • The <dpi> tag is a container for holding information about the printers resolution
    • If the resolution is known, place them accordingly following this example

<x>600</x>
<y>600</y>

• • • If the resolution is not known, insert the following:

<!--x unknown-->
<!--y unknown-->

foomatic-db/db/source/driver

• Naming convention

• The file name should be the driver name.

ljet4.xml

• • When the file reaches a size that is deemed to large, it should be split into groups by manufacturer.

Postscript-Oce.xml
Postscript-Toshiba.xml