openSUSE:Package description guidelines

Summary

The summary should be a short and concise description of the package, basically answering “What is it?” As such, it should not be a verb phrase (“What does it do”, ❌ "Computes fancy math"), but a nominal phrase (⭕ "Program/library/module/etc. for computing fancy math" or "Fancy math computation tool")
It 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 where adding finer details (like: text-based web-browser, browser with keyboard-only navigation, …) 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.

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 is cross-platform or runs on non-openSUSE targets like Windows, MacOS, etc.
Ensure a neutral point of view and avoid sensationalist words like: fast, modern, easy, simple, powerful, etc. Descriptions (and summaries) are not an advertisement, and the truthfulness of such properties can be questionable. (For a detailed list, see a later section below.)

Some of these points also apply to both summaries and descriptions.

Description

The description expands upon the summary. Try to answer what the software does and why someone would need or want to have the package. Be wary of copying descriptions verbatim from somewhere, since 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: it 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
- 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. The description 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 very long lines to work with, so consider wrapping it to the same width as the dashed line (66 characters).

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.

Author list

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

On the neutrality of descriptions

"fast": Every other software claims to be "fast". But "fast" compared to what? Because no software claims to be purposefully slow, your "fast" is really just average.
"free": Everything in openSUSE has to be free (save for openSUSE:Factory:NonFree), so this is not a property that makes the package stand out among all the others.
"pretty", "modern", "easy", "light", "simple", "powerful", ...: These are personal impressions and do not represent an unbiased view.
"fully-featured": Strictly speaking, there is an unlimited number of additional features any program can have, so by definition it cannot have all features yet. Better write that it implements the functionality of a certain specification.
extremely, ultra-: redundant adverbs that do not make the software any different than it already is
enterprise-ready/grade, award-winning, leading, winning: say no to buzzwords. They are a lie.