Pacman standards for the VDT

Having created a large number of Pacman packages for the VDT, I have become rather picky about how we setup our Pacman packages. While I may seem overly picky about these details, I strongly believe that they make the difference between a merely adequate installation experience and a superior installation experience. The goal for the VDT is to provide a superior installation experience.

With this goal in mind, I have developed a set of rules for Pacman packages in the VDT. I'm strict about these rules, and I yell and stomp my feet whenever people break them.

• Every package must log information into the vdt-install.log file. At a minimum, there must be a header that looks exactly like this, except with the correct software name and date:

  ##########
  # Building GPT 3.1 at Mon Jan 26 14:49:37 CST 2004
  ##########

  Yes, always use that number of hash symbols. It make it easy to look for inforation in the vdt-install.log file.

  In addition, the log should contain as much other information as possible. If you have a script that installs the software, everything should be put into the log file. If you build software, the output of the build should be put into the log file. This log file is essential, and has often helped us solve problems.

• If you want to give the user a bunch of information that does not require immeidate action do not print it to the screen. Instead, print a short note to the screen, and everything else in the postinstall directory. Usually information in the postinstall directory should be in the README. For example, you might say:

  We had to make certain choices about how to configure Condor. 
  For information about these choices and guidance on how to change
  them, please see the postinstall/README file.

• During installation, print as little information to the screen as possible. If there are serious errors, you can print those, and fail. Users do not need to see lots of messages about the random details of installation, like "updating .la files... changing gatekeeper config..." because they don't mean much to most users. Besides, it makes everything scroll off the screen, and they can no longer see what happened earlier. These messages can go into the log file, or the postinstall file.
• During installation, you should only ask users questions that are essential. If you can skip any questions and use reasonable defaults, please do so. If you have to have a lot of questions answered, perhaps they are best put into a script that users can run at post-installation time. Realize that few software packages are used by all users, and many users don't know the answers until they have worked with the software a bit. Have pity on the users, and don't expecdt too much out of them during installation.
• Packages must be installable as root and non-root. Many users want to install as non-root, to see how things work. This has been a selling point of the VDT. If some functionality has to be turned off because the installation was not done as root, so be it. Note this briefly on the screen, and provide details in the postinstall/README file about how to get back that additional functionality.
• Prefer to install software as binaries instead of compiling from source. Compiling from source is often tricky: users have poorly setup computers with outdated or missing tools, and compilation will fail. Also, compilation is usually slower. Yes, it is a pain to provide the correct binaries and decide which binaries to install, but it makes users happier. Think like a user, not a programmer. If you are sad that users don't have the source, install (but don't compile) the source as well, or provide a file that tells users how to get the source.
• Be careful about installing with the correct permissions. In some situations, when you unwind a tarball on a computer and you are root, the user and group are preserved, even though they may not make sense on this computer. Then users ask us things like, "why is this file owned by user 8407?".
• Pacman files must contain a clear description.
• Pacman files must contain a URL that tells users where to learn more about the package. Often the VDT web page is insufficient. For instance, for Monalisa, you want to give the Monalisa web page, not the VDT web page.
• Pacman files should be named with capital letters and hypens for spaces. For example, we have Globus-Environment.pacman. Pacman file names must end in .pacman, or Pacman can't find them. Pacman file names should rarely have version numbers in them.
• Pacman files should not have any tab characters in them, only spaces. This makes the files display neatly in both terminal windows and web browsers.