From 90a1ff5bab35f6e0d9918e63488f743fd355d78e Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 00:56:58 +0100 Subject: [PATCH 01/24] Create README.md --- README.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a018cdb --- /dev/null +++ b/README.md @@ -0,0 +1,23 @@ +# obs-service-tar-git +**OBS tar_git source service** + +Note that this README is not an exhaustive description or even a specification. It is merely a user contributed write-up providing some guidance how `tar_git` works. This write-up may have flaws or be fully errorneous at places; if you want to know something for sure, please read `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and its [shell script](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git), which provides all its functionality. + +Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`: The only publicly visible place where `tar_git` runs is [the SailfishOS-OBS](https://build.merproject.org/), where it is the only and mandatory service. + +### Parameters for OBS' `_service` file +See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service). + +### Parsing of Git tags +1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. +2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash are discarded. +3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. +4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "closest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. It then appends a date string and a short-hash, which are a clear indication that this code path was used. + +For example, when using `sfos4.2/0.3.0-2` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm`. + +#### The `token` parameter +When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) tag must match to, otherwise the tag is discarded. Note that such a tag is then subjected to the processing describes in steps 1 to 4, above. Hence for the aforemtioned example utilising "Storeman", `sfos` would be a suitable a token. Or when marking release versions with the string `release` in the release version (e.g., 1.2.3-release2`), the string `release` is a suitable `token` to filter for release versions. + +#### Examples +Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For example, by using the tags `1.2.3+git1`, `1.2.3~git1` or `1.2.3.git1` the whole string will become part of the RPM file-name, for `1.2.3-git1`, `git1/1.2.3` and `foo/1.2.3-bar` only the `1.2.3`. From b9ec24be84d9a95a6782073e1c3906ef03552bf2 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 01:41:42 +0100 Subject: [PATCH 02/24] Fixes, enhancements, link exemplary `_service` file --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a018cdb..9a2200d 100644 --- a/README.md +++ b/README.md @@ -6,18 +6,21 @@ Note that this README is not an exhaustive description or even a specification. Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`: The only publicly visible place where `tar_git` runs is [the SailfishOS-OBS](https://build.merproject.org/), where it is the only and mandatory service. ### Parameters for OBS' `_service` file -See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service). +See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. ### Parsing of Git tags 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash are discarded. 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "closest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. It then appends a date string and a short-hash, which are a clear indication that this code path was used. +4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. It then appends a `+`, the branch name in which the "nearest" tag was found, a `.` a date string, a `.1.g` and a short-hash (¿of the last commit?), which are a clear indication that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. +5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed at a package's page in the SailfishOS-OBS.. + +Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprised of `-1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. For example, when using `sfos4.2/0.3.0-2` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm`. #### The `token` parameter -When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) tag must match to, otherwise the tag is discarded. Note that such a tag is then subjected to the processing describes in steps 1 to 4, above. Hence for the aforemtioned example utilising "Storeman", `sfos` would be a suitable a token. Or when marking release versions with the string `release` in the release version (e.g., 1.2.3-release2`), the string `release` is a suitable `token` to filter for release versions. +When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) tag must match to, otherwise the tag is discarded. Note that such a tag is then subjected to the processing describes in steps 1 to 4, above. Hence for the aforementioned example utilising "Storeman", `sfos` would be a suitable a token. Or when marking release versions with the string `release` in the release version (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for release versions. #### Examples Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For example, by using the tags `1.2.3+git1`, `1.2.3~git1` or `1.2.3.git1` the whole string will become part of the RPM file-name, for `1.2.3-git1`, `git1/1.2.3` and `foo/1.2.3-bar` only the `1.2.3`. From feabf340431597732df656914bb82130f71f6b56 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 01:44:39 +0100 Subject: [PATCH 03/24] Fix two typos --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9a2200d..6e95a1c 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,11 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash are discarded. 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. 4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. It then appends a `+`, the branch name in which the "nearest" tag was found, a `.` a date string, a `.1.g` and a short-hash (¿of the last commit?), which are a clear indication that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. -5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed at a package's page in the SailfishOS-OBS.. +5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed at a package's page in the SailfishOS-OBS. -Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprised of `-1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. +Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprised of `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. -For example, when using `sfos4.2/0.3.0-2` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm`. +For example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm`. #### The `token` parameter When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) tag must match to, otherwise the tag is discarded. Note that such a tag is then subjected to the processing describes in steps 1 to 4, above. Hence for the aforementioned example utilising "Storeman", `sfos` would be a suitable a token. Or when marking release versions with the string `release` in the release version (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for release versions. From fb6facc9a7c4d96520e715dd07f89679f0eb65d4 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 01:47:03 +0100 Subject: [PATCH 04/24] Clarify by appending a half-sentence --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6e95a1c..a216d25 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprised of `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. -For example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm`. +For example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. #### The `token` parameter When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) tag must match to, otherwise the tag is discarded. Note that such a tag is then subjected to the processing describes in steps 1 to 4, above. Hence for the aforementioned example utilising "Storeman", `sfos` would be a suitable a token. Or when marking release versions with the string `release` in the release version (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for release versions. From d2697ecd300fec0da9d114b34bf72e3b42f28563 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 02:09:09 +0100 Subject: [PATCH 05/24] Add more information --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a216d25..f599513 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash are discarded. 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. It then appends a `+`, the branch name in which the "nearest" tag was found, a `.` a date string, a `.1.g` and a short-hash (¿of the last commit?), which are a clear indication that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. +4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "nearest" tag was found to construct a new version string, which comprises: The name of the "nearest" tag, a `+`, the branch name, a `.`, a date string (yyyymmddhhmmss), a `.1.`, sometimes a `g` (not yet analysed when) and a short-hash (¿of the last commit?), which are a clear indication that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. 5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed at a package's page in the SailfishOS-OBS. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprised of `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. From 5796e53b05da76ecd8f756900e391be351deaa05 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 02:21:49 +0100 Subject: [PATCH 06/24] Fix grammar and shorten --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f599513..03c9929 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,10 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash are discarded. 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "nearest" tag was found to construct a new version string, which comprises: The name of the "nearest" tag, a `+`, the branch name, a `.`, a date string (yyyymmddhhmmss), a `.1.`, sometimes a `g` (not yet analysed when) and a short-hash (¿of the last commit?), which are a clear indication that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. -5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed at a package's page in the SailfishOS-OBS. +4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "nearest" tag was found to construct a new version string, which comprises: The name of the "nearest" tag, a `+`, the branch name, a `.`, a date string (`yyyymmddhhmmss`), a `.1.`, sometimes a `g` (not yet analysed when) and a short-hash (¿of the last commit?), which indicate that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. +5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. -Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprised of `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. +Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. For example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. From fe9c3d99b2909b246ea9345a463eb850105b9737 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 02:27:38 +0100 Subject: [PATCH 07/24] Clarify "date-time string" --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 03c9929..e19bee6 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash are discarded. 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "nearest" tag was found to construct a new version string, which comprises: The name of the "nearest" tag, a `+`, the branch name, a `.`, a date string (`yyyymmddhhmmss`), a `.1.`, sometimes a `g` (not yet analysed when) and a short-hash (¿of the last commit?), which indicate that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. +4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "nearest" tag was found to construct a new version string, which comprises: The name of the "nearest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), a `.1.`, sometimes a `g` (missed to analyse when) and a short-hash (¿of the last commit?), which indicate that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. 5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. From c920379918b977546043dfe9d745d55c4df0bfb0 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 02:33:59 +0100 Subject: [PATCH 08/24] Fix think'o, grammar and shorten --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e19bee6..5db1203 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Note that, when a package is built by the SailfishOS-OBS, also a new release str For example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. #### The `token` parameter -When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) tag must match to, otherwise the tag is discarded. Note that such a tag is then subjected to the processing describes in steps 1 to 4, above. Hence for the aforementioned example utilising "Storeman", `sfos` would be a suitable a token. Or when marking release versions with the string `release` in the release version (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for release versions. +When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) tag must match to, otherwise the tag is discarded. Note that such a tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for. #### Examples Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For example, by using the tags `1.2.3+git1`, `1.2.3~git1` or `1.2.3.git1` the whole string will become part of the RPM file-name, for `1.2.3-git1`, `git1/1.2.3` and `foo/1.2.3-bar` only the `1.2.3`. From fc4f0889cd3168f46bec3686c3ee61dd76c5b841 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 03:18:18 +0100 Subject: [PATCH 09/24] Grammar fixes, exhaustive description for `g` --- README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5db1203..3041178 100644 --- a/README.md +++ b/README.md @@ -8,11 +8,11 @@ Side note: This is *not* about the regular OBS (Open Build Service) services (pl ### Parameters for OBS' `_service` file See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. -### Parsing of Git tags +### Parsing of Git tags referenced by the `revision` parameter 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. -2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash are discarded. -3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, `tar_git` [looks for the "nearest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter. Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "nearest" tag was found to construct a new version string, which comprises: The name of the "nearest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), a `.1.`, sometimes a `g` (missed to analyse when) and a short-hash (¿of the last commit?), which indicate that this code path was used, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` when the "nearest" tag found was `0.5.2-3`. +2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash is discarded. +3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter if set, otherwise it is discarded. +4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), a `.1.`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. 5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. @@ -24,3 +24,6 @@ When the `token` parameter contains a non-empty string (not a regular expression #### Examples Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For example, by using the tags `1.2.3+git1`, `1.2.3~git1` or `1.2.3.git1` the whole string will become part of the RPM file-name, for `1.2.3-git1`, `git1/1.2.3` and `foo/1.2.3-bar` only the `1.2.3`. + +### Changelog extraction / processing +\ From 2b42903077fab3c9a228b88e903e4262c5f6944c Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 15:43:20 +0100 Subject: [PATCH 10/24] Add usage reference, add missed sub-case, clarify --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3041178..288f806 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ Note that this README is not an exhaustive description or even a specification. Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`: The only publicly visible place where `tar_git` runs is [the SailfishOS-OBS](https://build.merproject.org/), where it is the only and mandatory service. ### Parameters for OBS' `_service` file -See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. +See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service), its [usage output](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L69-L83) for descriptions of the parameters and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. ### Parsing of Git tags referenced by the `revision` parameter 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash is discarded. 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter if set, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L960) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), a `.1.`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. +4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), a `.1.`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. 5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. From 5de18e19c372e20a71e7b7632aa986155ea7c012 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 20:16:16 +0100 Subject: [PATCH 11/24] Fix statement for number `..` --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 288f806..5ac0ce6 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash is discarded. 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter if set, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), a `.1.`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.1.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. +4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.5.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. 5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. From 5de21be8152411c85a1e6881646c33922d8f36f4 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 12 Feb 2023 20:19:18 +0100 Subject: [PATCH 12/24] Choose better number as example --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5ac0ce6..72ff946 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash is discarded. 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter if set, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.5.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. +4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. 5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. From 428f7456df192827cf296907503e4ec3d3ed1e22 Mon Sep 17 00:00:00 2001 From: olf Date: Wed, 15 Feb 2023 21:57:15 +0100 Subject: [PATCH 13/24] Rectify wording (there also is `webhook` service) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 72ff946..c57f687 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Note that this README is not an exhaustive description or even a specification. It is merely a user contributed write-up providing some guidance how `tar_git` works. This write-up may have flaws or be fully errorneous at places; if you want to know something for sure, please read `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and its [shell script](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git), which provides all its functionality. -Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`: The only publicly visible place where `tar_git` runs is [the SailfishOS-OBS](https://build.merproject.org/), where it is the only and mandatory service. +Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`: The only publicly visible place where `tar_git` runs is [the SailfishOS-OBS](https://build.merproject.org/), where it is the primary and mandatory service. ### Parameters for OBS' `_service` file See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service), its [usage output](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L69-L83) for descriptions of the parameters and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. From 1c61a2c0505be8c12a4b057b8d2fa227cb14b994 Mon Sep 17 00:00:00 2001 From: olf Date: Wed, 15 Mar 2023 02:28:10 +0100 Subject: [PATCH 14/24] Use a fixed commit as references, so ... they are still valid, if new code is committed, resulting in different line numbers --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c57f687..6f2782b 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ Note that this README is not an exhaustive description or even a specification. Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`: The only publicly visible place where `tar_git` runs is [the SailfishOS-OBS](https://build.merproject.org/), where it is the primary and mandatory service. ### Parameters for OBS' `_service` file -See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service), its [usage output](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L69-L83) for descriptions of the parameters and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. +See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service), its [usage output](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L69-L83) for descriptions of the parameters and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. ### Parsing of Git tags referenced by the `revision` parameter 1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. 2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash is discarded. -3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L406)) and originate from the branch provided by the `branch` parameter if set, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. +3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L406)) and originate from the branch provided by the `branch` parameter if set, otherwise it is discarded. +4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. 5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. From 05c8d68e477555019879a2944cef67326ee97eac Mon Sep 17 00:00:00 2001 From: olf Date: Wed, 15 Mar 2023 03:01:48 +0100 Subject: [PATCH 15/24] Completely overhaul document and align with the ["Analysis of tar_git" document in Storeman's wiki](https://github.com/storeman-developers/harbour-storeman/wiki/Analysis-of-tar_git) and vice versa. --- README.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 6f2782b..96c51ba 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,34 @@ # obs-service-tar-git -**OBS tar_git source service** +[**Jolla's OBS `tar_git` source service**](https://github.com/MeeGoIntegration/obs-service-tar-git) -Note that this README is not an exhaustive description or even a specification. It is merely a user contributed write-up providing some guidance how `tar_git` works. This write-up may have flaws or be fully errorneous at places; if you want to know something for sure, please read `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and its [shell script](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git), which provides all its functionality. +Note that this README is not an exhaustive description or even a specification. It is merely a user contributed write-up providing some guidance how `tar_git` works. This write-up may have flaws or be fully erroneous at places; if you want to know something for sure, please read `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and its [shell script](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git), which provides all its functionality. -Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`: The only publicly visible place where `tar_git` runs is [the SailfishOS-OBS](https://build.merproject.org/), where it is the primary and mandatory service. +Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`. The only publicly visible place where `tar_git` runs is the SailfishOS-OBS at [build.sailfishos.org](https://build.sailfishos.org/) (= [build.merproject.org](https://build.merproject.org/)), where it is the primary and mandatory service. -### Parameters for OBS' `_service` file +## Parameters for OBS `_service` files See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service), its [usage output](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L69-L83) for descriptions of the parameters and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. -### Parsing of Git tags referenced by the `revision` parameter -1. A valid tag for `tar_git` may contain at most a single dash ("-"). The sub-string starting at the dash is discarded. -2. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"). The "v" or the "vendor string" including the slash is discarded. -3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L406)) and originate from the branch provided by the `branch` parameter if set, otherwise it is discarded. +## Tag parsing +1. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"), see [first part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L376-L387): Both are cut out, a "v" is discarded, but a "vendor string" is prepended (without the slash) to the release field in the spec file (but see 6.). +2. A valid tag for `tar_git` may contain at most a single dash ("-"). If the sub-string starting with the dash conforms to the extended regular expression (ERE) `\-[[:alnum:]]+$`, it is put into the release field (without the dash and directly appended to a "vendor string") and the part up to the dash into the version field by `tar_git`. Hence a valid tag can be used to fully rewrite the version and release fields in the spec file, before OBS builds this package (but see 6.), see [second part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L389-L396). +3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written much more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. 4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. -5. The result of this overwrites the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. +5. The result of this processing replaces the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. +6. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. -Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. +#### Examples +Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For `1.2.3+git1`, `1.2.3~git1` and `1.2.3.git1` the whole string will be used as the processed`` string and become part of the RPM file-name; for `1.2.3-git4`, `git4/1.2.3` and `git/1.2.3-4` only the `1.2.3` and the release field will be initially set to `git4` for the latter three examples (which is later substituted by `1.I.1`). -For example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. +## The `token` parameter +When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for. -#### The `token` parameter -When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) tag must match to, otherwise the tag is discarded. Note that such a tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for. +## Source archive name +`tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any hyphens ("dashes": "-") to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. -#### Examples -Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For example, by using the tags `1.2.3+git1`, `1.2.3~git1` or `1.2.3.git1` the whole string will become part of the RPM file-name, for `1.2.3-git1`, `git1/1.2.3` and `foo/1.2.3-bar` only the `1.2.3`. +Hence the `%prep` section of a spec file **must** contain [`%autosetup`](https://rpm-software-management.github.io/rpm/manual/autosetup.html) or `%setup [-q] [-n %{name}-%{version}]`, but no other `-n` parameter can be used (which might as well be omitted)! -### Changelog extraction / processing +## Changelog extraction / processing \ + +## Notes +- This is a slightly shortened version of the ["Analysis of tar_git" document in Storeman's wiki](https://github.com/storeman-developers/harbour-storeman/wiki/Analysis-of-tar_git). From b7f5709418574bb5b29783c2614b5c7319cacb12 Mon Sep 17 00:00:00 2001 From: olf Date: Wed, 15 Mar 2023 03:06:15 +0100 Subject: [PATCH 16/24] Shorten and simplify wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 96c51ba..7e4fe9c 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Once understood how `tar_git`'s parsing of Git tags works, one can play with it: When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for. ## Source archive name -`tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any hyphens ("dashes": "-") to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. +`tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any dashes ("-") to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. Hence the `%prep` section of a spec file **must** contain [`%autosetup`](https://rpm-software-management.github.io/rpm/manual/autosetup.html) or `%setup [-q] [-n %{name}-%{version}]`, but no other `-n` parameter can be used (which might as well be omitted)! From 271253266dfb65a0728424e43975cd3ca9d83e94 Mon Sep 17 00:00:00 2001 From: olf Date: Wed, 15 Mar 2023 03:25:35 +0100 Subject: [PATCH 17/24] Reintroduce the "real life"-example, ... because it was referenced in the section below. --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 7e4fe9c..d67cf49 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,8 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s #### Examples Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For `1.2.3+git1`, `1.2.3~git1` and `1.2.3.git1` the whole string will be used as the processed`` string and become part of the RPM file-name; for `1.2.3-git4`, `git4/1.2.3` and `git/1.2.3-4` only the `1.2.3` and the release field will be initially set to `git4` for the latter three examples (which is later substituted by `1.I.1`). +As an "real life" example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. + ## The `token` parameter When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for. From 5dafc5ac1dd530b84fe40eb7e932609dbbfc7bda Mon Sep 17 00:00:00 2001 From: olf Date: Tue, 11 Apr 2023 22:23:16 +0200 Subject: [PATCH 18/24] Denote rebuild number --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d67cf49..1ff3411 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written much more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. 4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. 5. The result of this processing replaces the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. -6. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS and `.1.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. +6. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS, another `.` as separator, the number of builds for this revision of the package (i.e., the number of re-builds is one less), and `.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. #### Examples Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For `1.2.3+git1`, `1.2.3~git1` and `1.2.3.git1` the whole string will be used as the processed`` string and become part of the RPM file-name; for `1.2.3-git4`, `git4/1.2.3` and `git/1.2.3-4` only the `1.2.3` and the release field will be initially set to `git4` for the latter three examples (which is later substituted by `1.I.1`). From 72e4a2c2234da2e65e1f6b0ff4cfb5a1948204de Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 4 Feb 2024 18:18:20 +0100 Subject: [PATCH 19/24] [README.md] Make example more concise --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1ff3411..b278441 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Once understood how `tar_git`'s parsing of Git tags works, one can play with it: As an "real life" example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. ## The `token` parameter -When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g., `1.2.3-release2`), the string `release` is a suitable `token` to filter for. +When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g., `1.2.3-release2`), the string `-release` is a suitable `token` to filter for. ## Source archive name `tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any dashes ("-") to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. From 593b543b60cccb6c557c61f2427ae75bcb89ba2b Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 4 Feb 2024 18:20:45 +0100 Subject: [PATCH 20/24] [README.md] Omit commas after `i.e.` & `e.g.` (= British grammar) --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b278441..a4f5263 100644 --- a/README.md +++ b/README.md @@ -12,17 +12,17 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 1. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"), see [first part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L376-L387): Both are cut out, a "v" is discarded, but a "vendor string" is prepended (without the slash) to the release field in the spec file (but see 6.). 2. A valid tag for `tar_git` may contain at most a single dash ("-"). If the sub-string starting with the dash conforms to the extended regular expression (ERE) `\-[[:alnum:]]+$`, it is put into the release field (without the dash and directly appended to a "vendor string") and the part up to the dash into the version field by `tar_git`. Hence a valid tag can be used to fully rewrite the version and release fields in the spec file, before OBS builds this package (but see 6.), see [second part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L389-L396). 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written much more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L931-L999) which fulfils aforementioned rules (i.e., runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e., it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g., `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. +4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L931-L999) which fulfils aforementioned rules (i.e. runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e. it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g. `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. 5. The result of this processing replaces the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. -6. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS, another `.` as separator, the number of builds for this revision of the package (i.e., the number of re-builds is one less), and `.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. +6. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS, another `.` as separator, the number of builds for this revision of the package (i.e. the number of re-builds is one less), and `.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. #### Examples Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For `1.2.3+git1`, `1.2.3~git1` and `1.2.3.git1` the whole string will be used as the processed`` string and become part of the RPM file-name; for `1.2.3-git4`, `git4/1.2.3` and `git/1.2.3-4` only the `1.2.3` and the release field will be initially set to `git4` for the latter three examples (which is later substituted by `1.I.1`). -As an "real life" example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g., `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. +As an "real life" example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g. `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. ## The `token` parameter -When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e., unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g., `1.2.3-release2`), the string `-release` is a suitable `token` to filter for. +When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e. unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g. `1.2.3-release2`), the string `-release` is a suitable `token` to filter for. ## Source archive name `tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any dashes ("-") to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. From 82d6e3eb58c2523bc6130dffa87323e7dc28b5d0 Mon Sep 17 00:00:00 2001 From: olf Date: Sun, 16 Jun 2024 00:41:46 +0200 Subject: [PATCH 21/24] [README.md] Minor clarification --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a4f5263..53ece62 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ When the `token` parameter contains a non-empty string (not a regular expression ## Source archive name `tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any dashes ("-") to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. -Hence the `%prep` section of a spec file **must** contain [`%autosetup`](https://rpm-software-management.github.io/rpm/manual/autosetup.html) or `%setup [-q] [-n %{name}-%{version}]`, but no other `-n` parameter can be used (which might as well be omitted)! +Hence the `%prep` section of a spec file **must** contain [`%autosetup`](https://rpm-software-management.github.io/rpm/manual/autosetup.html) or `%setup [-q] [-n %{name}-%{version}]`, but no other `-n` parameter can be used (which might as well be omitted, then)! ## Changelog extraction / processing \ From 935be540312aef91750baa30ad4888a1f8ff8b3c Mon Sep 17 00:00:00 2001 From: olf Date: Mon, 9 Sep 2024 23:02:34 +0200 Subject: [PATCH 22/24] [README.md] Few, little rephrasings for clarity's sake --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 53ece62..5dbb57b 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,23 @@ # obs-service-tar-git [**Jolla's OBS `tar_git` source service**](https://github.com/MeeGoIntegration/obs-service-tar-git) -Note that this README is not an exhaustive description or even a specification. It is merely a user contributed write-up providing some guidance how `tar_git` works. This write-up may have flaws or be fully erroneous at places; if you want to know something for sure, please read `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and its [shell script](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git), which provides all its functionality. +Note that this README is not an exhaustive description or even a specification. It is merely a user-contributed write-up providing some guidance how `tar_git` works. This write-up may have weaknesses or be erroneous at places; if you want to know something for sure, please read `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service) and its [shell script](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git) which provides all functionality. -Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`. The only publicly visible place where `tar_git` runs is the SailfishOS-OBS at [build.sailfishos.org](https://build.sailfishos.org/) (= [build.merproject.org](https://build.merproject.org/)), where it is the primary and mandatory service. +Side note: This is *not* about the regular OBS (Open Build Service) services (plug-in modules) `tar_scm` or `git_tar`. The only publicly visible place where `tar_git` runs is the SailfishOS-OBS at [`build.sailfishos.org`](https://build.sailfishos.org/) (= [`build.merproject.org`](https://build.merproject.org/)), where it is the primary and mandatory service. ## Parameters for OBS `_service` files See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service), its [usage output](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L69-L83) for descriptions of the parameters and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. -## Tag parsing -1. A valid tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"), see [first part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L376-L387): Both are cut out, a "v" is discarded, but a "vendor string" is prepended (without the slash) to the release field in the spec file (but see 6.). -2. A valid tag for `tar_git` may contain at most a single dash ("-"). If the sub-string starting with the dash conforms to the extended regular expression (ERE) `\-[[:alnum:]]+$`, it is put into the release field (without the dash and directly appended to a "vendor string") and the part up to the dash into the version field by `tar_git`. Hence a valid tag can be used to fully rewrite the version and release fields in the spec file, before OBS builds this package (but see 6.), see [second part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L389-L396). +## Git tag parsing +1. A valid Git tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"), see [first part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L376-L387): Both are cut out, a "v" is discarded, but a "vendor string" is prepended (without the slash) to the release field in the spec file (but see 6.). +2. A valid Git tag for `tar_git` may contain at most a single dash ("-"). If the sub-string starting with the dash conforms to the extended regular expression (ERE) `\-[[:alnum:]]+$`, `tar_git` puts it into the release field (without the dash and directly appended to a "vendor string") and the part up to the dash into the version field. Hence a valid tag can be used to fully rewrite the version and release fields in the spec file, before OBS builds this package (but see 6.), see [second part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L389-L396). 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written much more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. -4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, `tar_git` [looks for the "closest" tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L931-L999) which fulfils aforementioned rules (i.e. runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e. it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g. `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch. +4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, then `tar_git` [looks for the "closest" Git tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L931-L999) which fulfils aforementioned rules (i.e. runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e. it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g. `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch! 5. The result of this processing replaces the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. 6. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS, another `.` as separator, the number of builds for this revision of the package (i.e. the number of re-builds is one less), and `.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. #### Examples -Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For `1.2.3+git1`, `1.2.3~git1` and `1.2.3.git1` the whole string will be used as the processed`` string and become part of the RPM file-name; for `1.2.3-git4`, `git4/1.2.3` and `git/1.2.3-4` only the `1.2.3` and the release field will be initially set to `git4` for the latter three examples (which is later substituted by `1.I.1`). +Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For `1.2.3+git1`, `1.2.3~git1` and `1.2.3.git1` the whole string will be used as the processed `` string and become part of the RPM file-name; for `1.2.3-git4`, `git4/1.2.3` and `git/1.2.3-4` only the `1.2.3` will, and the release field will be initially set to `git4` for the latter three examples (which is later substituted by `1.I.1`). As an "real life" example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g. `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. @@ -27,7 +27,7 @@ When the `token` parameter contains a non-empty string (not a regular expression ## Source archive name `tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any dashes ("-") to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. -Hence the `%prep` section of a spec file **must** contain [`%autosetup`](https://rpm-software-management.github.io/rpm/manual/autosetup.html) or `%setup [-q] [-n %{name}-%{version}]`, but no other `-n` parameter can be used (which might as well be omitted, then)! +Hence the `%prep` section of a spec file **must** contain [`%autosetup`](https://rpm-software-management.github.io/rpm/manual/autosetup.html) or `%setup [-q] [-n %{name}-%{version}]`, but no other `-n` parameter can be used (which might as well be omitted, then) and `-q` is demanded by most spec file linters (e.g. `rpmlint`)! ## Changelog extraction / processing \ From a5789ebc7b5307f7e0e0ea665211cce3e381a76a Mon Sep 17 00:00:00 2001 From: olf Date: Mon, 9 Sep 2024 23:06:39 +0200 Subject: [PATCH 23/24] [README.md] Better use of monospaced text attribute --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5dbb57b..f08c082 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ Side note: This is *not* about the regular OBS (Open Build Service) services (pl See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/master/tar_git.service), its [usage output](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L69-L83) for descriptions of the parameters and an [exemplary `_service`](https://build.merproject.org/package/view_file/sailfishos:chum:testing/harbour-storeman-installer/_service) file. ## Git tag parsing -1. A valid Git tag for `tar_git` may be prefixed by either a small "v" or a "vendor string" ending in a slash ("/"), see [first part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L376-L387): Both are cut out, a "v" is discarded, but a "vendor string" is prepended (without the slash) to the release field in the spec file (but see 6.). -2. A valid Git tag for `tar_git` may contain at most a single dash ("-"). If the sub-string starting with the dash conforms to the extended regular expression (ERE) `\-[[:alnum:]]+$`, `tar_git` puts it into the release field (without the dash and directly appended to a "vendor string") and the part up to the dash into the version field. Hence a valid tag can be used to fully rewrite the version and release fields in the spec file, before OBS builds this package (but see 6.), see [second part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L389-L396). +1. A valid Git tag for `tar_git` may be prefixed by either a small letter `v` or a "vendor string" ending in a slash (`/`), see [first part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L376-L387): Both are cut out, a `v` is discarded, but a "vendor string" is prepended (without the slash) to the release field in the spec file (but see 6.). +2. A valid Git tag for `tar_git` may contain at most a single dash (`-`). If the sub-string starting with the dash conforms to the extended regular expression (ERE) `\-[[:alnum:]]+$`, `tar_git` puts it into the release field (without the dash and directly appended to a "vendor string") and the part up to the dash into the version field. Hence a valid tag can be used to fully rewrite the version and release fields in the spec file, before OBS builds this package (but see 6.), see [second part of the function `get_tagver_from_tag`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L389-L396). 3. The resulting, stripped tag must conform to the extended regular expression (ERE) `^[[:digit:]]+\.[[:alnum:].~+]*$` (but is actually [written much more complicated](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L406)) and originate from the branch provided by the `branch` parameter, otherwise it is discarded. 4. If there is no valid tag or if a commit ID (short-hash) was provided, or if a `branch` parameter is set and either no `revision` is set or in this Git branch commits exist newer than the tag referenced by the `revision` parameter, then `tar_git` [looks for the "closest" Git tag in the function `set_versha`](https://github.com/MeeGoIntegration/obs-service-tar-git/blob/3affb34c2c1d0f565afec8761f451e67cf46661b/tar_git#L931-L999) which fulfils aforementioned rules (i.e. runs through steps 1 to 3 with it), but misses to filter for the branch provided by the `branch` parameter (i.e. it searches in *all* branches). Still, it uses the value of the `branch` parameter, or if none is provided, the branch name in which the "closest" tag was found to construct a new version string, which comprises: The processed name of the "closest" tag, a `+`, the branch name, a `.`, a date-time string (`YYYYMMDDhhmmss`), the number of commits since the "closest" tag in the branch it resides enclosed in dots `..`, a `g` if newer commits exist in the branch referenced by `branch` than the tag referenced by `revision`, and the short-hash of the latest commit, resulting in, e.g. `0.5.2+main.20230129011931.6.g584263a` with `0.5.2-3` as "closest" tag found. Note that if the "closest" tag determined does not originate from the branch provided by the `branch` parameter, still this parameter is inserted in the constructed string, despite using a Git checkout from another branch! 5. The result of this processing replaces the original `Version:` string in the RPM spec file, which can be viewed on a package's page in the SailfishOS-OBS. From 62f79306b06a2610c3867c0bccce14f2d8019676 Mon Sep 17 00:00:00 2001 From: olf Date: Mon, 9 Sep 2024 23:43:14 +0200 Subject: [PATCH 24/24] [README.md] Consitency in formatting and two clarifications --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f08c082..260e383 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ See `tar_git`'s [interface definition](https://github.com/MeeGoIntegration/obs-s 6. Note that, when a package is built by the SailfishOS-OBS, also a new release string is constructed, comprising a `1.`, the package revision at OBS, another `.` as separator, the number of builds for this revision of the package (i.e. the number of re-builds is one less), and `.jolla`. This is *not* visible in the processed RPM spec file of a package, because it is done while building a package. #### Examples -Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For `1.2.3+git1`, `1.2.3~git1` and `1.2.3.git1` the whole string will be used as the processed `` string and become part of the RPM file-name; for `1.2.3-git4`, `git4/1.2.3` and `git/1.2.3-4` only the `1.2.3` will, and the release field will be initially set to `git4` for the latter three examples (which is later substituted by `1.I.1`). +Once understood how `tar_git`'s parsing of Git tags works, one can play with it: For `1.2.3+git1`, `1.2.3~git1` and `1.2.3.git1` the whole string will be used as the processed `` string and become part of the RPM file-name; for `1.2.3-git4`, `git4/1.2.3` and `git/1.2.3-4` only the `1.2.3` will, and the release field will be initially set to `git4` for the latter three examples (which is later substituted by `1.I.1`). As an "real life" example, when using `sfos4.2/0.3.0-5` as a tag name for the `harbour-storeman` app, this results in, e.g. `harbour-storeman-0.3.0-1.13.1.jolla.armv7hl.rpm` as a final package name. @@ -25,9 +25,9 @@ As an "real life" example, when using `sfos4.2/0.3.0-5` as a tag name for the `h When the `token` parameter contains a non-empty string (not a regular expression), this string is used as a sub-string an original (i.e. unprocessed) Git tag must match to, otherwise the tag is discarded. Note that such a Git tag is then subjected to the processing described in steps 1 to 4, above. Hence for the aforementioned example using the `harbour-storeman` app, `sfos` would be a suitable `token`. Or when marking release versions with the string `release` in Git tags (e.g. `1.2.3-release2`), the string `-release` is a suitable `token` to filter for. ## Source archive name -`tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any dashes ("-") to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. +`tar_git` always renames the source archive to `-.`, using the processed Git tag as ``. While retaining the name and the extension, there is no way to achieve `--.` as its source archive, because the processing prevents any dashes (`-`) to be retained in the processed `` string. If no valid {https|http|ftp} path to a source archive is provided, it performs a Git check-out using the tag determined as described above. -Hence the `%prep` section of a spec file **must** contain [`%autosetup`](https://rpm-software-management.github.io/rpm/manual/autosetup.html) or `%setup [-q] [-n %{name}-%{version}]`, but no other `-n` parameter can be used (which might as well be omitted, then) and `-q` is demanded by most spec file linters (e.g. `rpmlint`)! +Hence the `%prep` section of a spec file **must** contain [`%autosetup`](https://rpm-software-management.github.io/rpm/manual/autosetup.html) or `%setup [-q] [-n %{name}-%{version}]`, but no other parameter can be used for the option `-n` (which might as well be omitted, because this is the default format string) and `-q` is demanded by most spec file linters (e.g. `rpmlint`)! ## Changelog extraction / processing \