Skip to content

docs: update dev/topic/packaging/pkgdesc-guideline #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JulianDroske wants to merge 1 commit into
base: new
Choose a base branch
from
Open

docs: update dev/topic/packaging/pkgdesc-guideline #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 16 additions & 16 deletions dev/topic/packaging/pkgdesc-guideline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ dateCreated: 2025-06-04T13:35:33.099Z

# Guideline for Writing pkgdesc

It has been found that our pkgdesc entries are messy in format and some of them don't provide effective information or are too redundant. This documentation serves as a guideline for clear, informative, and precise pkgdescs.
It has been found that our pkgdesc entries are messy in format and some of them do not provide effective information or are too redundant. This documentation serves as a guideline for clear, informative, and precise pkgdescs.

## Use a full sentence

The description should be a full sentence starting with an UPPERCASE letter.
The description should be a full sentence starting with an UPPERCASE letter, but with NO trailing periods.

### BAD

Expand All @@ -24,9 +24,7 @@ The description should be a full sentence starting with an UPPERCASE letter.

> Stacking wayland compositor with look and feel from openbox

## Avoid trailing periods

Although it's a full sentence, pkgdesc appears in places where trailing periods look redundant or unnatural, for example,
since pkgdesc appears in places where trailing periods look redundant or unnatural, for example,

```
$ pacman -Si ctags
Expand All @@ -51,11 +49,11 @@ Build Date : Mon May 19 03:24:37 2025
Validated By : MD5 Sum SHA-256 Sum Signature
```

Description becomes the only item that comes with trailing punctuaction.
where the description becomes the only item that comes with trailing punctuaction.

## Be descriptive instead of definition
## More descriptive, less definitive

Descriptions are meant to provide an overview of the package. Please make sure one hasn't heard of the package is able to understand its purpose from the description.
Descriptions are expected to provide a brief overview of a package, so that most people can understand the purpose of it from the description with little prior knowledge.

### BAD

Expand All @@ -65,23 +63,25 @@ Descriptions are meant to provide an overview of the package. Please make sure o

> Basic, default toolset for building eweOS packages

pkgdesc shouldn't be an A.D. for the project.
## Be neutral

A pkgdesc should not be an advertisement for the project.

Therefore, try not to use biased phrases which could make it less objective. Take an example for `zstd`:

### BAD

> An extremely fast hash algorithm
> Extremely fast, efficient and robust compression algorithm

### GOOD

> A fast, non-cryptographic hash algorithm.
> Fast real-time compression algorithm

while the word `extremely` contains strong emotion, `efficient` and `robust` draw positive opinion on it, they are not ideal options.


## About the Documentation

It used to be an RFC which could be found at [this GitHub issue](https://github.com/eweOS/packages/issues/4036).

During drafting,

- [AOSC packaging style](https://wiki.aosc.io/developer/packaging/package-styling-manual/)

is taken as reference.
During drafting, the [AOSC packaging style](https://wiki.aosc.io/developer/packaging/package-styling-manual/) is taken as a reference.