> Producing and Maintaining Packages
Overview
The package summary (pkg.summary) and description (pkg.description) are two package attributes that may be included in a package. The values of these attributes are used when information about the package is presented in a form that is typically viewed by a human.
pkg.summary - Summary
A short summary of the package generally used as a human readable title. The summary should be kept to approximately 30 characters to avoid truncations when used in some scenarios. Set via the pkg.summary package attribute. The pkg.summary attribute is analogous to the SVR4 package NAME attribute.
pkg.description - Description
A one or two paragraph description of the package. This attribute should build on the summary/title provided in the pkg.summary attribute. The two attributes should work together to provide a fairly comprehensive textual description of the package. The contents of this attribute will be displayed in the Description tab of the Update Tool GUI. Set via the pkg.description package attribute.
For example the summary will appear in the Update Tool GUI's Component list as well as in the component's Description tab. The package description will also appear in the component's Description tab in the Update Tool. These attributes may also appear when probing the contents of a repository using the repository's browser interface.
These attributes assist the user in identifying a particular package as well as understanding its role on the system and relationship to other packages.
Best Practices
| # | Title | Description |
|---|---|---|
| 1. | Summary | |
| 1.1 | 30 characters of less with capitalized words | A short summary of the package generally used as a human readable title. Should not be more than 30 characters long. Words should be capitalized as appropriate for a title. |
| 1.2 | Identify component at start of summary | Use words that identify the product the component is associated with at the start of the summary. This will help to ensure the component is listed in the expected position when a sort on the component title is performed in certain applications such as the Update Tool. For example "GlassFish Documentation" or "GlassFish Administration Console" are better than "Documentation for GlassFish" or "Admin Console - GlassFish". |
| 1.3 | Use classification attribute for general role or category | Defer qualifying the general role of the component to the category mapping for this package (see [XXX] for more information on category mappings). For example, if the package is an add-on module for GlassFish, don't consume valuable characters in the pkg.summary field by mentioning that it is a GlassFish add-on. Defer to the category mapping to provide this qualification. |
| 1.4 | Avoid including version number | Avoid including the version number in the package summary unless the version number is also included in the package name and install location. |
| 1.5 | Avoid including release qualifiers | Specifying Alpha, Beta, etc: Since the package version fields support only numerical values, when you need to convey that a package is of a certain quality level, e.g. "alpha", "beta", etc, you are encouraged to represent the quality level in the summary and description attributes of your package. As the package progresses to high levels of quality, you can modify the value of these attributes to convey the revised level of quality of the package. For example: "GlassFish V3 Core (Beta)" |
| 2. | Description | |
| 2.1 | Explain the role | First, briefly explain the role of the component in the context of this distribution. For example, if the component is an add-on to GlassFish, explain this role in one or two sentences. |
| 2.2 | Declare cluster packages up front | Alternatively, if the package is cluster package that only contains a list of dependencies, then declare this fact up front. For example: This package is a cluster package containing dependencies on all <component name> packages of a specific recent version. It can be used to conveniently install all <component name> components... |
| 2.3 | Include introductory information | After the role information or cluster declaration, copy and paste the introductory or overview description of the component that likely already exists in your project's documentation and/or web site. |
Details
Summary Example
Update Tool is a multi-platform, network repository based tool that helps you manage software installations layered on top of your existing operating system. The tool enables you to easily add, update and remove components. The built-in desktop notification feature helps keep you aware of available updates. Update Tool leverages the Image Packaging System (IPS) technology from OpenSolaris.org to provide an efficient and robust means of managing software installations.
Sign up or Log in to add a comment or watch this page.