#912 clarify summary and description section
Opened a year ago by bex. Modified a year ago
Unknown source description_udpate  into  master

@@ -437,17 +437,29 @@

  

  === BuildRequires based on pkg-config

  

- Fedora packages which use `+pkg-config+` to build against a library (e.g. 'foo') on which they depend, *SHOULD* express their build dependency correctly as `+pkgconfig(foo)+`. For more information, see xref:PkgConfigBuildRequires.adoc[Packaging:PkgConfigBuildRequires].

+ Fedora packages which use `+pkg-config+` to build against a library (e.g. 'foo') on which they depend, *SHOULD* express their build dependency correctly as `+pkgconfig(foo)+`.

+ For more information, see xref:PkgConfigBuildRequires.adoc[Packaging:PkgConfigBuildRequires].

  

  == Conditional build-time dependencies

  

- If the spec file contains conditional dependencies selected based on presence of optional `+--with(out) foo+` arguments to `+rpmbuild+`, build the source RPM to be submitted with the default options, i.e., so that none of these arguments are present in the `+rpmbuild+` command line. The reason is that those requirements get "serialized" into the resulting source RPM, i.e., the conditionals no longer apply.

+ If the spec file contains conditional dependencies selected based on presence of optional `+--with(out) foo+` arguments to `+rpmbuild+`, build the source RPM to be submitted with the default options, i.e., so that none of these arguments are present in the `+rpmbuild+` command line.

+ The reason is that those requirements get "serialized" into the resulting source RPM, i.e., the conditionals no longer apply.

  

  == Summary and description

  

- The summary should be a short and concise description of the package. The description expands upon this. 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.Fedora_, or similar, if you feel this is necessary. Also, please make sure that there are no lines in the description longer than 80 characters.

+ The summary should be a short and concise description of the package. The description should expand upon this.

  

- Please put personal preferences aside and use American English spelling in the summary and description. Packages can contain additional translated summary/description for supported Non-English languages, if available.

+ === Dos and Don'ts

+ 

+ * The summary should be 80 characters/columns or less.

+   If you are using something other than ASCII look at a utf length function or something similar to calculate the column count.

+ * Make sure that there are no lines in the description longer than 80 characters/columns.

+   If you are using something other than ASCII look at a utf length function or something similar to calculate the column count.

+ * 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.Fedora_, or similar, if you feel this is necessary.

+ * For consistency, we use the American English spelling and grammar rules in the summary and description.  

+   Packages can contain additional translated summary/description for supported Non-English languages, if available.

  

  === Trademarks in Summary or Description

  

no initial comment

@vondruch I am not opposed to removing it, I was thinking about someone scanning the index at the top of this very long page and trying to let them know there was easy to digest advice.

80 characters is a pretty useless definition in an UTF-8 world (in UTF-8 you have pre-composed and de-composed symbols, some codepoints have zero-width, and anyway most codepoints take more than one byte).

You want 80 columns, not 80 characters or bytes. And then most of the languages are barely getting to the point where they can count codepoints, not bytes, let alone distinguish between codepoints with or without width.

https://src.fedoraproject.org/rpms/redhat-rpm-config/blob/master/f/common.lua#_159 uses utf8.len() to compute line widths, it seems to be the best thing available today, pretty sure than in 10 years it will be replaced by something more accurate.

rebased onto 0c238510f18f1d9066461c362b74ab8d1ff478c6

a year ago

updated - additional comments welcome.

rebased onto 68f5f18

a year ago
Metadata