[-- Attachment #1: Type: text/plain, Size: 1704 bytes --] There is a new pull request by ericonr against master on the void-packages repository https://github.com/ericonr/void-packages lines https://github.com/void-linux/void-packages/pull/29897 [WIP] Manual: add 80 column line break suggestion. Also rework most of the language in the Introduction. <!-- Mark items with [x] where applicable --> #### General - [ ] This is a new package and it conforms to the [quality requirements](https://github.com/void-linux/void-packages/blob/master/Manual.md#quality-requirements) #### Have the results of the proposed changes been tested? - [ ] I use the packages affected by the proposed changes on a regular basis and confirm this PR works for me - [ ] I generally don't use the affected packages but briefly tested this PR <!-- If GitHub CI cannot be used to validate the build result (for example, if the build is likely to take several hours), make sure to [skip CI](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration). When skipping CI, uncomment and fill out the following section. Note: for builds that are likely to complete in less than 2 hours, it is not acceptable to skip CI. --> <!-- #### Does it build and run successfully? (Please choose at least one native build and, if supported, at least one cross build. More are better.) - [ ] I built this PR locally for my native architecture, (ARCH-LIBC) - [ ] I built this PR locally for these architectures (if supported. mark crossbuilds): - [ ] aarch64-musl - [ ] armv7l - [ ] armv6l-musl --> [ci skip] Picking up from #29765 A patch file from https://github.com/void-linux/void-packages/pull/29897.patch is attached [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: github-pr-lines-29897.patch --] [-- Type: text/x-diff, Size: 1909 bytes --] From aa7576feb373ec0e277a863eca589626d31ed8cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Nogueira?= <erico.erc@gmail.com> Date: Wed, 31 Mar 2021 00:19:13 -0300 Subject: [PATCH] Manual: add 80 column line break suggestion. Also rework most of the language in the Introduction. --- Manual.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/Manual.md b/Manual.md index 4439865e1d73..ab275744e6ce 100644 --- a/Manual.md +++ b/Manual.md @@ -76,17 +76,19 @@ packages for XBPS, the `Void Linux` native packaging system. <a id="Introduction"></a> ## Introduction -The `void-packages` repository contains all `source` packages that are the -recipes to download, compile and build binary packages for `Void`. -Those `source` package files are called `templates`. +The `void-packages` repository contains all the +recipes to download, compile and build binary packages for Void Linux. +These `source` package files are called `templates`. -The `template files` are `GNU bash` shell scripts that must define some required/optional +The `template' files are `GNU bash` scripts that define some optional or required `variables` and `functions` that are processed by `xbps-src` (the package builder) to generate the resulting binary packages. -By convention, all templates start with a comment briefly explaining what they -are. In addition, pkgname and version can't have any characters in them that -would require them to be quoted, so they are not quoted. +By convention, all templates start with a comment saying that it is a +`template file` for a certain package. In addition, `pkgname` and `version` can't +contain any characters in that would require them to be quoted, so they are not quoted. +Most of the lines should be kept under 80 columns; variables that list many values +can be split into new lines. A simple `template` example is as follows:
[-- Attachment #1: Type: text/plain, Size: 203 bytes --] New review comment by sgn on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r604817625 Comment: It's ``` `template` ``` instead of ``` `template' ```
[-- Attachment #1: Type: text/plain, Size: 238 bytes --] New review comment by Chocimier on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r605063318 Comment: This fits better into description of variables, as there are more restictions on version.
[-- Attachment #1: Type: text/plain, Size: 193 bytes --] New review comment by Chocimier on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r605063947 Comment: ... with continuation indented by one space.
[-- Attachment #1: Type: text/plain, Size: 247 bytes --] New review comment by Chocimier on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r605065567 Comment: Simply "shell scripts that define variables and functions that are processed by `xbps-src`" maybe?
[-- Attachment #1: Type: text/plain, Size: 1709 bytes --] There is an updated pull request by ericonr against master on the void-packages repository https://github.com/ericonr/void-packages lines https://github.com/void-linux/void-packages/pull/29897 [WIP] Manual: add 80 column line break suggestion. Also rework most of the language in the Introduction. <!-- Mark items with [x] where applicable --> #### General - [ ] This is a new package and it conforms to the [quality requirements](https://github.com/void-linux/void-packages/blob/master/Manual.md#quality-requirements) #### Have the results of the proposed changes been tested? - [ ] I use the packages affected by the proposed changes on a regular basis and confirm this PR works for me - [ ] I generally don't use the affected packages but briefly tested this PR <!-- If GitHub CI cannot be used to validate the build result (for example, if the build is likely to take several hours), make sure to [skip CI](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration). When skipping CI, uncomment and fill out the following section. Note: for builds that are likely to complete in less than 2 hours, it is not acceptable to skip CI. --> <!-- #### Does it build and run successfully? (Please choose at least one native build and, if supported, at least one cross build. More are better.) - [ ] I built this PR locally for my native architecture, (ARCH-LIBC) - [ ] I built this PR locally for these architectures (if supported. mark crossbuilds): - [ ] aarch64-musl - [ ] armv7l - [ ] armv6l-musl --> [ci skip] Picking up from #29765 A patch file from https://github.com/void-linux/void-packages/pull/29897.patch is attached [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: github-pr-lines-29897.patch --] [-- Type: text/x-diff, Size: 3617 bytes --] From 02af52ee30bc2fe5c71a8ec3e6a5ef86079d5a80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Nogueira?= <erico.erc@gmail.com> Date: Wed, 31 Mar 2021 00:19:13 -0300 Subject: [PATCH] Manual: add 80 column line break suggestion. Also: - rework most of the language in the Introduction - move note about special characters in pkgname or version - note restrictions to version field are caused partly by xbps-checkvers --- Manual.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/Manual.md b/Manual.md index 4439865e1d73..2105d7a2eea3 100644 --- a/Manual.md +++ b/Manual.md @@ -76,17 +76,19 @@ packages for XBPS, the `Void Linux` native packaging system. <a id="Introduction"></a> ## Introduction -The `void-packages` repository contains all `source` packages that are the -recipes to download, compile and build binary packages for `Void`. -Those `source` package files are called `templates`. +The `void-packages` repository contains all the +recipes to download, compile and build binary packages for Void Linux. +These `source` package files are called `templates`. -The `template files` are `GNU bash` shell scripts that must define some required/optional -`variables` and `functions` that are processed by `xbps-src` (the package builder) -to generate the resulting binary packages. +The `template` files are shell scripts that define `variables` and `functions` +to be processed by `xbps-src`, the package builder, to generate binary packages. +The shell used by `xbps-src` is GNU bash; `xbps-src` doesn't aim to be +compatible with POSIX `sh`. -By convention, all templates start with a comment briefly explaining what they -are. In addition, pkgname and version can't have any characters in them that -would require them to be quoted, so they are not quoted. +By convention, all templates start with a comment saying that it is a +`template file` for a certain package. Most of the lines should be kept under 80 +columns; variables that list many values can be split into new lines, with the +continuation in the next line indented by one space. A simple `template` example is as follows: @@ -447,10 +449,9 @@ Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, cus Note: `MIT`, `BSD`, `ISC` and custom licenses require the license file to be supplied with the binary package. -- `maintainer` A string in the form of `name <user@domain>`. The - email for this field must be a valid email that you can be reached - at. Packages using `users.noreply.github.com` emails will not be - accepted. +- `maintainer` A string in the form of `name <user@domain>`. The email for this field +must be a valid email that you can be reached at. Packages using +`users.noreply.github.com` emails will not be accepted. - `pkgname` A string with the package name, matching `srcpkgs/<pkgname>`. @@ -461,7 +462,11 @@ the generated `binary packages` have been modified. - `short_desc` A string with a brief description for this package. Max 72 chars. - `version` A string with the package version. Must not contain dashes or underscore -and at least one digit is required. Shell's variable substition usage is not allowed. +and at least one digit is required. Using bash's pattern substitution, prefix and suffix +matching isn't supported, since this field needs to be parsed by `xbps-checkvers(1)`. + +Neither `pkgname` or `version` should contain special characters which make it necessary +to quote them, so they shouldn't be quoted in the template. <a id="optional_vars"></a> #### Optional variables
[-- Attachment #1: Type: text/plain, Size: 213 bytes --] New review comment by ericonr on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r608968024 Comment: I still wanted to mention bash, let me know if it's okay this way.
[-- Attachment #1: Type: text/plain, Size: 177 bytes --] New comment by ericonr on void-packages repository https://github.com/void-linux/void-packages/pull/29897#issuecomment-815165169 Comment: Thanks both for the review, updated.
[-- Attachment #1: Type: text/plain, Size: 1703 bytes --] There is an updated pull request by ericonr against master on the void-packages repository https://github.com/ericonr/void-packages lines https://github.com/void-linux/void-packages/pull/29897 Manual: add 80 column line break suggestion. Also rework most of the language in the Introduction. <!-- Mark items with [x] where applicable --> #### General - [ ] This is a new package and it conforms to the [quality requirements](https://github.com/void-linux/void-packages/blob/master/Manual.md#quality-requirements) #### Have the results of the proposed changes been tested? - [ ] I use the packages affected by the proposed changes on a regular basis and confirm this PR works for me - [ ] I generally don't use the affected packages but briefly tested this PR <!-- If GitHub CI cannot be used to validate the build result (for example, if the build is likely to take several hours), make sure to [skip CI](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration). When skipping CI, uncomment and fill out the following section. Note: for builds that are likely to complete in less than 2 hours, it is not acceptable to skip CI. --> <!-- #### Does it build and run successfully? (Please choose at least one native build and, if supported, at least one cross build. More are better.) - [ ] I built this PR locally for my native architecture, (ARCH-LIBC) - [ ] I built this PR locally for these architectures (if supported. mark crossbuilds): - [ ] aarch64-musl - [ ] armv7l - [ ] armv6l-musl --> [ci skip] Picking up from #29765 A patch file from https://github.com/void-linux/void-packages/pull/29897.patch is attached [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: github-pr-lines-29897.patch --] [-- Type: text/x-diff, Size: 3617 bytes --] From defd7d81911038e1b8c59027c4b7ea3c78c3f8e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Nogueira?= <erico.erc@gmail.com> Date: Wed, 31 Mar 2021 00:19:13 -0300 Subject: [PATCH] Manual: add 80 column line break suggestion. Also: - rework most of the language in the Introduction - move note about special characters in pkgname or version - note restrictions to version field are caused partly by xbps-checkvers --- Manual.md | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/Manual.md b/Manual.md index 4439865e1d73..2105d7a2eea3 100644 --- a/Manual.md +++ b/Manual.md @@ -76,17 +76,19 @@ packages for XBPS, the `Void Linux` native packaging system. <a id="Introduction"></a> ## Introduction -The `void-packages` repository contains all `source` packages that are the -recipes to download, compile and build binary packages for `Void`. -Those `source` package files are called `templates`. +The `void-packages` repository contains all the +recipes to download, compile and build binary packages for Void Linux. +These `source` package files are called `templates`. -The `template files` are `GNU bash` shell scripts that must define some required/optional -`variables` and `functions` that are processed by `xbps-src` (the package builder) -to generate the resulting binary packages. +The `template` files are shell scripts that define `variables` and `functions` +to be processed by `xbps-src`, the package builder, to generate binary packages. +The shell used by `xbps-src` is GNU bash; `xbps-src` doesn't aim to be +compatible with POSIX `sh`. -By convention, all templates start with a comment briefly explaining what they -are. In addition, pkgname and version can't have any characters in them that -would require them to be quoted, so they are not quoted. +By convention, all templates start with a comment saying that it is a +`template file` for a certain package. Most of the lines should be kept under 80 +columns; variables that list many values can be split into new lines, with the +continuation in the next line indented by one space. A simple `template` example is as follows: @@ -447,10 +449,9 @@ Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, cus Note: `MIT`, `BSD`, `ISC` and custom licenses require the license file to be supplied with the binary package. -- `maintainer` A string in the form of `name <user@domain>`. The - email for this field must be a valid email that you can be reached - at. Packages using `users.noreply.github.com` emails will not be - accepted. +- `maintainer` A string in the form of `name <user@domain>`. The email for this field +must be a valid email that you can be reached at. Packages using +`users.noreply.github.com` emails will not be accepted. - `pkgname` A string with the package name, matching `srcpkgs/<pkgname>`. @@ -461,7 +462,11 @@ the generated `binary packages` have been modified. - `short_desc` A string with a brief description for this package. Max 72 chars. - `version` A string with the package version. Must not contain dashes or underscore -and at least one digit is required. Shell's variable substition usage is not allowed. +and at least one digit is required. Using bash's pattern substitution, prefix and suffix +matching isn't supported, since this field needs to be parsed by `xbps-checkvers(1)`. + +Neither `pkgname` or `version` should contain special characters which make it necessary +to quote them, so they shouldn't be quoted in the template. <a id="optional_vars"></a> #### Optional variables
[-- Attachment #1: Type: text/plain, Size: 283 bytes --] New review comment by Chocimier on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r609001469 Comment: I'm for not using variables in version and constructing other variables from version, as xupdate from xtools' issue works better then.
[-- Attachment #1: Type: text/plain, Size: 173 bytes --] New review comment by Chocimier on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r609001810 Comment: Any content change here?
[-- Attachment #1: Type: text/plain, Size: 239 bytes --] New review comment by Chocimier on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r609005955 Comment: Both forms of mentioning bash are fine. Just wanted clean up `required or optional` quirk.
[-- Attachment #1: Type: text/plain, Size: 2300 bytes --] New review comment by ericonr on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r609021872 Comment: I can't find `xupdate`... This would mean that the following packages are "incorrect", and we'd have to agree that they are better off with raw `version` fields: ``` srcpkgs/EmptyEpsilon/template:version="${_ver_major}.${_ver_minor}.${_ver_patch}" srcpkgs/ImageMagick/template:version="${_majorver}.${_patchver}" srcpkgs/ImageMagick6/template:version="${_majorver}.${_patchver}" srcpkgs/cross-x86_64-w64-mingw32/template:version=$_mingw_version srcpkgs/dialog/template:version="${_distver}.${_date}" srcpkgs/dmraid/template:version="${_distver}.${_patchver}" srcpkgs/ftgl/template:version="${_distver}${_distrcver}" srcpkgs/gcc-multilib/template:version=${_majorver}.1pre1 srcpkgs/gcc/template:version=${_patchver}pre1 srcpkgs/gcc6/template:version=${_minorver}.0 srcpkgs/google-chrome/template:version="${_chromeVersion}.${_chromeRevision}" srcpkgs/hfsprogs/template:version="${_distver}.linux${_patchver}" srcpkgs/j/template:version=${_vmaj}.${_vmin} srcpkgs/libax25/template:version="${_distver}${_patchver}" srcpkgs/libedit/template:version="${_datever}.${_distver}" srcpkgs/libpurple-facebook/template:version=${_version}.${_rev} srcpkgs/libreadline8/template:version="${_dist_ver}.${_patch_ver}" srcpkgs/libtcd/template:version=${_distver}.${_distrev} srcpkgs/lynx/template:version="${_distver}.${_patchver}" srcpkgs/man-pages-posix/template:version="${_distver}${_revver}" srcpkgs/mcwm/template:version="${_distver}.${_patchver}" srcpkgs/openjdk10-bootstrap/template:version="10.0.2p${_jdk_build}" srcpkgs/openjdk11/template:version="${_java_ver}.${_java_min_ver}.${_java_sec_ver}+${_jdk_update}" srcpkgs/openjdk7-bootstrap/template:version="${_java_ver}u${_jdk_update}b${_jdk_build}" srcpkgs/openjdk8/template:version="${_java_ver}u${_jdk_update}b${_jdk_build}" srcpkgs/openjdk9-bootstrap/template:version="9.0.4p${_jdk_build}" srcpkgs/pcc/template:version=${_distver}.${_snapshot} srcpkgs/python3-apsw/template:version=${_distver}${_patchver} srcpkgs/simutron/template:version=1.0.1.${_rev} srcpkgs/tcc/template:version=${_distver}.${_voidver} srcpkgs/x264/template:version="${_snap_date}.${_snap_rev}" ```
[-- Attachment #1: Type: text/plain, Size: 213 bytes --] New review comment by ericonr on void-packages repository https://github.com/void-linux/void-packages/pull/29897#discussion_r609022220 Comment: No, just fixing indentation to match the other items in the block.
[-- Attachment #1: Type: text/plain, Size: 1703 bytes --] There is an updated pull request by ericonr against master on the void-packages repository https://github.com/ericonr/void-packages lines https://github.com/void-linux/void-packages/pull/29897 Manual: add 80 column line break suggestion. Also rework most of the language in the Introduction. <!-- Mark items with [x] where applicable --> #### General - [ ] This is a new package and it conforms to the [quality requirements](https://github.com/void-linux/void-packages/blob/master/Manual.md#quality-requirements) #### Have the results of the proposed changes been tested? - [ ] I use the packages affected by the proposed changes on a regular basis and confirm this PR works for me - [ ] I generally don't use the affected packages but briefly tested this PR <!-- If GitHub CI cannot be used to validate the build result (for example, if the build is likely to take several hours), make sure to [skip CI](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration). When skipping CI, uncomment and fill out the following section. Note: for builds that are likely to complete in less than 2 hours, it is not acceptable to skip CI. --> <!-- #### Does it build and run successfully? (Please choose at least one native build and, if supported, at least one cross build. More are better.) - [ ] I built this PR locally for my native architecture, (ARCH-LIBC) - [ ] I built this PR locally for these architectures (if supported. mark crossbuilds): - [ ] aarch64-musl - [ ] armv7l - [ ] armv6l-musl --> [ci skip] Picking up from #29765 A patch file from https://github.com/void-linux/void-packages/pull/29897.patch is attached [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: github-pr-lines-29897.patch --] [-- Type: text/x-diff, Size: 3671 bytes --] From b927f28259564f28451288f5cb524b9e75b608f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Nogueira?= <erico.erc@gmail.com> Date: Wed, 31 Mar 2021 00:19:13 -0300 Subject: [PATCH] Manual: add 80 column line break suggestion. Also: - rework most of the language in the Introduction - move note about special characters in pkgname or version - note restrictions to version field are caused partly by xbps-checkvers --- Manual.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/Manual.md b/Manual.md index 4439865e1d73..82f8142cee5f 100644 --- a/Manual.md +++ b/Manual.md @@ -76,17 +76,19 @@ packages for XBPS, the `Void Linux` native packaging system. <a id="Introduction"></a> ## Introduction -The `void-packages` repository contains all `source` packages that are the -recipes to download, compile and build binary packages for `Void`. -Those `source` package files are called `templates`. +The `void-packages` repository contains all the +recipes to download, compile and build binary packages for Void Linux. +These `source` package files are called `templates`. -The `template files` are `GNU bash` shell scripts that must define some required/optional -`variables` and `functions` that are processed by `xbps-src` (the package builder) -to generate the resulting binary packages. +The `template` files are shell scripts that define `variables` and `functions` +to be processed by `xbps-src`, the package builder, to generate binary packages. +The shell used by `xbps-src` is GNU bash; `xbps-src` doesn't aim to be +compatible with POSIX `sh`. -By convention, all templates start with a comment briefly explaining what they -are. In addition, pkgname and version can't have any characters in them that -would require them to be quoted, so they are not quoted. +By convention, all templates start with a comment saying that it is a +`template file` for a certain package. Most of the lines should be kept under 80 +columns; variables that list many values can be split into new lines, with the +continuation in the next line indented by one space. A simple `template` example is as follows: @@ -447,10 +449,9 @@ Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, cus Note: `MIT`, `BSD`, `ISC` and custom licenses require the license file to be supplied with the binary package. -- `maintainer` A string in the form of `name <user@domain>`. The - email for this field must be a valid email that you can be reached - at. Packages using `users.noreply.github.com` emails will not be - accepted. +- `maintainer` A string in the form of `name <user@domain>`. The email for this field +must be a valid email that you can be reached at. Packages using +`users.noreply.github.com` emails will not be accepted. - `pkgname` A string with the package name, matching `srcpkgs/<pkgname>`. @@ -461,7 +462,12 @@ the generated `binary packages` have been modified. - `short_desc` A string with a brief description for this package. Max 72 chars. - `version` A string with the package version. Must not contain dashes or underscore -and at least one digit is required. Shell's variable substition usage is not allowed. +and at least one digit is required. Using bash's pattern substitution and prefix and +suffix matching isn't supported, since this field needs to be parsed by +`xbps-checkvers(1)`. Using variables in this field should be avoided. + +Neither `pkgname` or `version` should contain special characters which make it necessary +to quote them, so they shouldn't be quoted in the template. <a id="optional_vars"></a> #### Optional variables
[-- Attachment #1: Type: text/plain, Size: 1703 bytes --] There is an updated pull request by ericonr against master on the void-packages repository https://github.com/ericonr/void-packages lines https://github.com/void-linux/void-packages/pull/29897 Manual: add 80 column line break suggestion. Also rework most of the language in the Introduction. <!-- Mark items with [x] where applicable --> #### General - [ ] This is a new package and it conforms to the [quality requirements](https://github.com/void-linux/void-packages/blob/master/Manual.md#quality-requirements) #### Have the results of the proposed changes been tested? - [ ] I use the packages affected by the proposed changes on a regular basis and confirm this PR works for me - [ ] I generally don't use the affected packages but briefly tested this PR <!-- If GitHub CI cannot be used to validate the build result (for example, if the build is likely to take several hours), make sure to [skip CI](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration). When skipping CI, uncomment and fill out the following section. Note: for builds that are likely to complete in less than 2 hours, it is not acceptable to skip CI. --> <!-- #### Does it build and run successfully? (Please choose at least one native build and, if supported, at least one cross build. More are better.) - [ ] I built this PR locally for my native architecture, (ARCH-LIBC) - [ ] I built this PR locally for these architectures (if supported. mark crossbuilds): - [ ] aarch64-musl - [ ] armv7l - [ ] armv6l-musl --> [ci skip] Picking up from #29765 A patch file from https://github.com/void-linux/void-packages/pull/29897.patch is attached [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: github-pr-lines-29897.patch --] [-- Type: text/x-diff, Size: 3710 bytes --] From 8b143fef3d2a1f2a1a1b7f7eeb235f3708c1745e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Nogueira?= <erico.erc@gmail.com> Date: Wed, 31 Mar 2021 00:19:13 -0300 Subject: [PATCH] Manual: add 80 column line break suggestion. Also: - rework most of the language in the Introduction - move note about special characters in pkgname or version - note restrictions to version field are caused partly by xbps-checkvers - fix indentation of 'maintainer' item --- Manual.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/Manual.md b/Manual.md index 4439865e1d73..82f8142cee5f 100644 --- a/Manual.md +++ b/Manual.md @@ -76,17 +76,19 @@ packages for XBPS, the `Void Linux` native packaging system. <a id="Introduction"></a> ## Introduction -The `void-packages` repository contains all `source` packages that are the -recipes to download, compile and build binary packages for `Void`. -Those `source` package files are called `templates`. +The `void-packages` repository contains all the +recipes to download, compile and build binary packages for Void Linux. +These `source` package files are called `templates`. -The `template files` are `GNU bash` shell scripts that must define some required/optional -`variables` and `functions` that are processed by `xbps-src` (the package builder) -to generate the resulting binary packages. +The `template` files are shell scripts that define `variables` and `functions` +to be processed by `xbps-src`, the package builder, to generate binary packages. +The shell used by `xbps-src` is GNU bash; `xbps-src` doesn't aim to be +compatible with POSIX `sh`. -By convention, all templates start with a comment briefly explaining what they -are. In addition, pkgname and version can't have any characters in them that -would require them to be quoted, so they are not quoted. +By convention, all templates start with a comment saying that it is a +`template file` for a certain package. Most of the lines should be kept under 80 +columns; variables that list many values can be split into new lines, with the +continuation in the next line indented by one space. A simple `template` example is as follows: @@ -447,10 +449,9 @@ Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, cus Note: `MIT`, `BSD`, `ISC` and custom licenses require the license file to be supplied with the binary package. -- `maintainer` A string in the form of `name <user@domain>`. The - email for this field must be a valid email that you can be reached - at. Packages using `users.noreply.github.com` emails will not be - accepted. +- `maintainer` A string in the form of `name <user@domain>`. The email for this field +must be a valid email that you can be reached at. Packages using +`users.noreply.github.com` emails will not be accepted. - `pkgname` A string with the package name, matching `srcpkgs/<pkgname>`. @@ -461,7 +462,12 @@ the generated `binary packages` have been modified. - `short_desc` A string with a brief description for this package. Max 72 chars. - `version` A string with the package version. Must not contain dashes or underscore -and at least one digit is required. Shell's variable substition usage is not allowed. +and at least one digit is required. Using bash's pattern substitution and prefix and +suffix matching isn't supported, since this field needs to be parsed by +`xbps-checkvers(1)`. Using variables in this field should be avoided. + +Neither `pkgname` or `version` should contain special characters which make it necessary +to quote them, so they shouldn't be quoted in the template. <a id="optional_vars"></a> #### Optional variables
[-- Attachment #1: Type: text/plain, Size: 1703 bytes --] There is an updated pull request by ericonr against master on the void-packages repository https://github.com/ericonr/void-packages lines https://github.com/void-linux/void-packages/pull/29897 Manual: add 80 column line break suggestion. Also rework most of the language in the Introduction. <!-- Mark items with [x] where applicable --> #### General - [ ] This is a new package and it conforms to the [quality requirements](https://github.com/void-linux/void-packages/blob/master/Manual.md#quality-requirements) #### Have the results of the proposed changes been tested? - [ ] I use the packages affected by the proposed changes on a regular basis and confirm this PR works for me - [ ] I generally don't use the affected packages but briefly tested this PR <!-- If GitHub CI cannot be used to validate the build result (for example, if the build is likely to take several hours), make sure to [skip CI](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration). When skipping CI, uncomment and fill out the following section. Note: for builds that are likely to complete in less than 2 hours, it is not acceptable to skip CI. --> <!-- #### Does it build and run successfully? (Please choose at least one native build and, if supported, at least one cross build. More are better.) - [ ] I built this PR locally for my native architecture, (ARCH-LIBC) - [ ] I built this PR locally for these architectures (if supported. mark crossbuilds): - [ ] aarch64-musl - [ ] armv7l - [ ] armv6l-musl --> [ci skip] Picking up from #29765 A patch file from https://github.com/void-linux/void-packages/pull/29897.patch is attached [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: github-pr-lines-29897.patch --] [-- Type: text/x-diff, Size: 3710 bytes --] From 9a09adb63cc005f0f89fa2468d8eea859131ccb7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89rico=20Nogueira?= <erico.erc@gmail.com> Date: Wed, 31 Mar 2021 00:19:13 -0300 Subject: [PATCH] Manual: add 80 column line break suggestion. Also: - rework most of the language in the Introduction - move note about special characters in pkgname or version - note restrictions to version field are caused partly by xbps-checkvers - fix indentation of 'maintainer' item --- Manual.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/Manual.md b/Manual.md index 4439865e1d73..8c2afbaca71d 100644 --- a/Manual.md +++ b/Manual.md @@ -76,17 +76,19 @@ packages for XBPS, the `Void Linux` native packaging system. <a id="Introduction"></a> ## Introduction -The `void-packages` repository contains all `source` packages that are the -recipes to download, compile and build binary packages for `Void`. -Those `source` package files are called `templates`. +The `void-packages` repository contains all the +recipes to download, compile and build binary packages for Void Linux. +These `source` package files are called `templates`. -The `template files` are `GNU bash` shell scripts that must define some required/optional -`variables` and `functions` that are processed by `xbps-src` (the package builder) -to generate the resulting binary packages. +The `template` files are shell scripts that define `variables` and `functions` +to be processed by `xbps-src`, the package builder, to generate binary packages. +The shell used by `xbps-src` is GNU bash; `xbps-src` doesn't aim to be +compatible with POSIX `sh`. -By convention, all templates start with a comment briefly explaining what they -are. In addition, pkgname and version can't have any characters in them that -would require them to be quoted, so they are not quoted. +By convention, all templates start with a comment saying that it is a +`template file` for a certain package. Most of the lines should be kept under 80 +columns; variables that list many values can be split into new lines, with the +continuation in the next line indented by one space. A simple `template` example is as follows: @@ -447,10 +449,9 @@ Multiple licenses should be separated by commas, Example: `GPL-3.0-or-later, cus Note: `MIT`, `BSD`, `ISC` and custom licenses require the license file to be supplied with the binary package. -- `maintainer` A string in the form of `name <user@domain>`. The - email for this field must be a valid email that you can be reached - at. Packages using `users.noreply.github.com` emails will not be - accepted. +- `maintainer` A string in the form of `name <user@domain>`. The email for this field +must be a valid email that you can be reached at. Packages using +`users.noreply.github.com` emails will not be accepted. - `pkgname` A string with the package name, matching `srcpkgs/<pkgname>`. @@ -461,7 +462,12 @@ the generated `binary packages` have been modified. - `short_desc` A string with a brief description for this package. Max 72 chars. - `version` A string with the package version. Must not contain dashes or underscore -and at least one digit is required. Shell's variable substition usage is not allowed. +and at least one digit is required. Using bash's pattern substitution and prefix and +suffix matching isn't supported, since this field needs to be parsed by +`xbps-checkvers(1)`. Using variables in this field should be avoided. + +Neither `pkgname` or `version` should contain special characters which make it +necessary to quote them, so they shouldn't be quoted in the template. <a id="optional_vars"></a> #### Optional variables
[-- Attachment #1: Type: text/plain, Size: 1549 bytes --] There's a merged pull request on the void-packages repository Manual: add 80 column line break suggestion. https://github.com/void-linux/void-packages/pull/29897 Description: Also rework most of the language in the Introduction. <!-- Mark items with [x] where applicable --> #### General - [ ] This is a new package and it conforms to the [quality requirements](https://github.com/void-linux/void-packages/blob/master/Manual.md#quality-requirements) #### Have the results of the proposed changes been tested? - [ ] I use the packages affected by the proposed changes on a regular basis and confirm this PR works for me - [ ] I generally don't use the affected packages but briefly tested this PR <!-- If GitHub CI cannot be used to validate the build result (for example, if the build is likely to take several hours), make sure to [skip CI](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md#continuous-integration). When skipping CI, uncomment and fill out the following section. Note: for builds that are likely to complete in less than 2 hours, it is not acceptable to skip CI. --> <!-- #### Does it build and run successfully? (Please choose at least one native build and, if supported, at least one cross build. More are better.) - [ ] I built this PR locally for my native architecture, (ARCH-LIBC) - [ ] I built this PR locally for these architectures (if supported. mark crossbuilds): - [ ] aarch64-musl - [ ] armv7l - [ ] armv6l-musl --> [ci skip] Picking up from #29765