Instructions for Contributors

Contents

Instructions for Contributors

 

We are grateful for any contribution to the database and to the OpenPrinting 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 or our software, 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 eric (at) linuxfoundation.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 our Drupal system by clicking the link in the upper right corner. Click on "Settings" 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. If you do not have Bazaar write access, 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
bzr branch http://bzr.openprinting.org/cups-filters
bzr branch http://bzr.openprinting.org/misc/common-printing-dialog

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 of Foomatic for bug fixes and small changes, and the development line for new database entries and bigger changes in the software.

If you have write access to Bazaar, use the non-anonymous download:

bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic/foomatic-filters
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic/foomatic-db-engine
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic/foomatic-db
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic/foomatic-db-nonfree
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic-4.0/foomatic-filters
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic-4.0/foomatic-db-engine
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic-3.0/foomatic-filters
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic-3.0/foomatic-db-engine
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/cups-filters
bzr branch https+urllib://<user>@bzr.linuxfoundation.org/openprinting/misc/common-printing-dialog

"<user>" has to be replaced by your Linux Foundation user name. You will be asked for your password before download and whenever you access the server on a further step. Do not add the password to the URLs. The only way to remember the password is to create a file named authentication.conf in your ~/.bazaar directory containing an entry like this

[Linux Foundation Bazaar Repositories]
scheme=https
host=bzr.linuxfoundation.org
path=/
user=...
password=...

with your user name and password filled in. If the file already exists, append the entry to it.

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. If you do not have write access to our BZR repositories, generate a bundle file (this is a diff with all meta information about the change history):

bzr bundle > mychanges.bundle

If you have write access, continue at step 12.

11. 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. If the changes are related to a bug report, attach the bundle to the appropriate bug report and describe it in the accompanying comment. Step 12 is not relevant for you then.

12. If you have write access to our repositories, you can directly upload your changes. Do the "bzr push" command appropriate to the package to which you want to commit:

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

bzr push --remember https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic-4.0/foomatic-filters
bzr push --remember https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic-4.0/foomatic-db-engine
bzr push --remember https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic-3.0/foomatic-filters
bzr push --remember https+urllib://<user>@bzr.linuxfoundation.org/openprinting/foomatic-3.0/foomatic-db-engine
bzr push --remember https+urllib://<user>@bzr.linuxfoundation.org/openprinting/cups-filters
bzr push --remember https+urllib://<user>@bzr.linuxfoundation.org/openprinting/misc/common-printing-dialog

"<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".

13. (Optional) For more info about using Bazaar, go to section "Documentation" 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
Groups: