Home Wiki > openSUSE:Package description guidelines
Sign up | Login

openSUSE:Package description guidelines

tagline: From openSUSE

Summary

  • It should be a short and concise description of the package. Basically, "What is it?"
  • The summary should fit all standard situations and not assume any special context.
  • It should be helpful alone, in alphabetically sorted or unsorted lists of some selected packages, and in alphabetically sorted or unsorted lists of all packages.
    • This means that, for example, "Client side libraries" or "Files mandatory for development" as a summary is not enough, because what client, what development?
  • It should describe the package's main function and point out any special properties of the package to support the user comparing similar packages. For example, the two words "Web Browser" summarize any web browser, but using additional adjectives (like minimalistic, text-based) helps characterize a specific package.
  • It should not end in a period. If this bothers you from a grammatical point of view, sit down, take a deep breath, and get over it.


  • Don't just copy descriptions, but:
  • Be concise. Avoiding fillers like "free", "open", "open-source", "for (GNU/)Linux", etc. Everything in openSUSE (minus very few exceptions) already has all these properties and it need not be repeated in every package's description.
  • Ensure relevance. There is no point in mentioning that a package runs on non-openSUSE targets like Windows, MacOS, etc.
  • Ensure a neutral point of view (NPOV) by avoiding biased or simply pointless words: fast, pretty, modern, easy, light-weight, fully-featured, simple, powerful; extremely, ultra, enterprise-ready/grade, award-winning, leading. Descriptions are not a marketplace.

Description

The description expands upon the summary. Try to answer what it does and why someone would need or want to have the package. Be wary of copying descriptions verbatim from somewhere, as they may be biased, contain errors, or wording unnecessary for openSUSE. If in doubt, say it in your own words.

  • Avoid mentioning irrelevant things:
    • Project aims/goals: What matters is what the package can do, and what it does now. Its aims and visions of what it will do in some future time does not help the user at present.
    • Portability: does not matter that this program is also available for other platforms. The user is looking at the package in the context of openSUSE.
    • Pointless/redundant words (see Summary section)
    • Testimonials
  • Do not include installation instructions in the description; it is not a manual. If the package requires some manual configuration or there are other important instructions to the user, refer the user to the documentation in the package. Add a README.SUSE, or similar, if you feel this is necessary.
  • There is no need to painstakingly list every aspect there is. The ideal size range of a description is between 160 and 700 characters. (That upper end amounts to some 9-line block of pure prose or about 15 lines if you consider a mix of prose and a bulleted list for example.)
  • Authorship information of the software does not belong into the description.

The package description should help the user decide on the right package for the intended purpose without needing to test other similar packages first. This is the right place to inform the user more precisely about a package's functionality. It should contain further information about features and differences from other, comparable packages. If a package could harm a user's installation, the description should contain clear notes on its potential risks or side effects.

Even though both the Qt and ncurses frontends for YaST2 know to automatically convert description text to HTML and then wrap it for display, consider that people will be using various editors for the .spec file itself and would prefer not to have figuratively endless lines to work with, so consider wrapping it.

HTML properties

Please respect these HTML properties: Empty lines result in paragraphs. In a list environment, empty lines end the list. Linebreaks result in a single space, that means that a line break has no special effect. An unnumbered list environment starts with a line that starts with an asterisk or a minus sign followed by at least one whitespace. A line which continues a list item starts with at least two whitespaces

Also, the description should not exceed a reasonable size, more than 20 lines is probably too much.

Please put personal preferences aside and use American English spelling in the summary and description. The RPM spec file contains only the English version of Summary and Description to keep the RPM database small. The localizations are managed by YaST.

The list of authors at the end of the description should not be included any more [NB:since summer 2011]. If you plan on honoring the authors with a mention, use a separate AUTHORS file for the credits. If the file is not already part of the upstream package, you should create one, and use it like this:

Source2:        AUTHORS
...
%setup
cp %{S:2} .
...
%files
%doc AUTHORS

Trademarks in Summary or Description

Packagers should be careful how they use trademarks in Summary or Description. There are a few rules to follow:

  • Never use "(TM)" or "(R)" (or the Unicode equivalents, ™/®). It is incredibly complicated to use these properly, so it is actually safer for us to not use them at all.
  • Use trademarks in a way that is not ambiguous. Avoid phrasing like "similar to" or "like". Some examples:
  • BAD: It is similar to Adobe Photoshop.
  • GOOD: It supports Adobe Photoshop PSD files, ...
  • BAD: A Linux version of Microsoft Office
  • GOOD: A word-processor with support for Microsoft Office DOC files

If you are not sure, ask yourself, is there any chance someone may get confused and think that this package is the trademarked item? When in doubt, try to leave the trademark out.