Skip to content

Commit

Permalink
README, issue templates, log some status data etc. (#21)
Browse files Browse the repository at this point in the history
* Instruct reporters to attach the log-file

* Instruct reporters to attach the log-file

* Update README.md

* Enhancements and a fix

* Straighten convoluted sentence

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Update README.md

* Output some status data, first

* Pre release version increase
  • Loading branch information
Olf0 authored Mar 20, 2023
2 parents 143ead3 + 372818f commit f631841
Show file tree
Hide file tree
Showing 5 changed files with 29 additions and 14 deletions.
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/bug-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ assignees: ''
#### STEPS TO REPRODUCE


#### ATTACH LOG-FILE

Upload the log-file from `/var/log/sailfishos-chum-gui-installer.log.txt` here.


#### ADDITIONAL INFORMATION

<sub>\[Please consider which other pieces of information may be relevant: Denote if this is not always reproducible, if this is a regression (then name to which older version), attach relevant data such as log files or the systemd journal, provide screenshots etc.\]</sub>
5 changes: 5 additions & 0 deletions .github/ISSUE_TEMPLATE/help-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ assignees: ''
#### STEPS TO REPRODUCE


#### ATTACH LOG-FILE

Upload the log-file from `/var/log/sailfishos-chum-gui-installer.log.txt` here.


#### ADDITIONAL INFORMATION

<sub>\[Please consider which other pieces of information may be relevant: Denote if this is not always reproducible, if this is a regression (then name to which older version), attach relevant data such as log files or the systemd journal, provide screenshots etc.\]</sub>
26 changes: 13 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,34 @@
# SailfishOS:Chum GUI Installer

**The SailfishOS:Chum GUI Installer performs the initial installation of the [SailfishOS:Chum GUI application](https://github.com/sailfishos-chum/sailfishos-chum-gui). SailfishOS:Chum GUI Installer selects, downloads and installs the correct variant of the SailfishOS:Chum GUI application built for the CPU-architecture of the device and the installed SailfishOS release from the SailfishOS-OBS.**
**The SailfishOS:Chum GUI Installer performs the initial installation of the [SailfishOS:Chum GUI application](https://github.com/sailfishos-chum/sailfishos-chum-gui#readme). SailfishOS:Chum GUI Installer selects, downloads and installs the correct variant of the SailfishOS:Chum GUI application built for the CPU-architecture of the device and the installed SailfishOS release from the SailfishOS-OBS.**

The SailfishOS:Chum GUI Installer works on any SailfishOS release ≥&nbsp;3.1.0 and all supported CPU-architectures (armv7hl, i486 and aarch64). The current SailfishOS:Chum GUI Installer RPM can be obtained from [its "latest release" page at GitHub](https://github.com/sailfishos-chum/sailfishos-chum-gui-installer/releases/latest), [OpenRepos.net](https://openrepos.net/content/olf/sailfishos-chum-gui-installer) and [the SailfishOS-OBS](https://build.merproject.org/package/show/sailfishos:chum/sailfishos-chum-gui-installer).
The SailfishOS:Chum GUI Installer works on any SailfishOS release ≥&nbsp;3.1.0 and all supported CPU-architectures (armv7hl, i486 and aarch64). The current SailfishOS:Chum GUI Installer RPM can be obtained from its ["latest release" page at GitHub](https://github.com/sailfishos-chum/sailfishos-chum-gui-installer/releases/latest), [OpenRepos.net](https://openrepos.net/content/olf/sailfishos-chum-gui-installer) and [the SailfishOS-OBS](https://build.merproject.org/package/show/sailfishos:chum/sailfishos-chum-gui-installer).

### Important notes

* If you experience issues with SailfishOS:Chum GUI Installer, please take a look at its log file `/var/log/sailfishos-chum-gui-installer.log.txt`. If that does not reveal to you what is going wrong, please check first if an issue report describing this issue [is already filed at GitHub](https://github.com/sailfishos-chum/sailfishos-chum-gui-installer/issues), then you might file a new issue report there and attach the log file to it, or enhance an extant bug report.
* If you experience issues with the SailfishOS:Chum GUI Installer, please take a look at its log file `/var/log/sailfishos-chum-gui-installer.log.txt`. If that does not reveal to you what is going wrong, please check first if an issue report describing this issue [is already filed at GitHub](https://github.com/sailfishos-chum/sailfishos-chum-gui-installer/issues), then you might file a new issue report there and attach the log file to it, or enhance an extant bug report.
* If you experience issues when installing, removing or updating packages after a SailfishOS upgrade, try running `devel-su pkcon refresh` in a terminal app.
* When the SailfishOS:Chum GUI Installer fails to install anything (i.e, a minute after installing it the icon of the SailfishOS:Chum GUI application has not appeared on the launcher / desktop), most likely the preceding or the following bullet point is the reason.
* Before software can be build for a SailfishOS release at the SailfishOS-OBS, Jolla must create [a corresponding "download on demand (DoD)" OBS-repository](https://build.merproject.org/project/subprojects/sailfishos). It may take a little time after a new SailfishOS release is published before the corresponding "DoD" repository is being made available, during which installing or updating the SailfishOS:Chum GUI application by itself or the SailfishOS:Chum GUI Installer on a device with the new SailfishOS release already installed will not succeed, because the SailfishOS:Chum GUI application cannot be compiled for this new SailfishOS release by the Sailfish-OBS, yet; consequently this is always the case during the "closed beta (cBeta)" phase of a new SailfishOS release. Hence one has to manually download and install, or update the SailfishOS:Chum GUI application built for the last prior SailfishOS GA via `pkcon install-local <downloaded RPM file>` release (e.g., from [its releases section at GitHub](https://github.com/sailfishos-chum/sailfishos-chum-gui/releases) or [the SailfishOS:Chum repository](https://build.merproject.org/project/show/sailfishos:chum/sailfishos-chum-gui)) then, and hope that there is no change in the new SailfishOS release, which breaks the SailfishOS:Chum GUI application; if there is, please report that soon at [the SailfishOS:Chum GUI application's issue tracker](https://github.com/sailfishos-chum/sailfishos-chum-gui/issues).
* Disclaimer: The SailfishOS:Chum GUI application and SailfishOS:Chum GUI Installer may still have flaws, kill your kittens or break your SailfishOS installation! Although this is very unlikely after years of testing by many users, new flaws may be introduced in any release (as for any software). Be aware, that the license you implicitly accept by using the SailfishOS:Chum GUI and its installer excludes any liability.
* Before software can be build for a SailfishOS release at the SailfishOS-OBS, Jolla must create a [corresponding "download on demand (DoD)" OBS-repository](https://build.merproject.org/project/subprojects/sailfishos). It may take a little time after a new SailfishOS release is published before the corresponding "DoD" repository is being made available, during which installing the SailfishOS:Chum GUI application by the SailfishOS:Chum GUI Installer or updating the SailfishOS:Chum GUI application by itself on a device with the new SailfishOS release already installed does not work, because the SailfishOS:Chum GUI application cannot be compiled for this new SailfishOS release at the Sailfish-OBS, yet; consequently this is always the case for "closed beta (cBeta)" releases of SailfishOS. In such a situation one has to manually download the SailfishOS:Chum GUI application built for the last prior SailfishOS "general availability (GA)" release (e.g., from [the SailfishOS:Chum repository](https://build.merproject.org/project/show/sailfishos:chum/sailfishos-chum-gui)), then install or update the SailfishOS:Chum GUI application via `pkcon install-local <downloaded RPM file>`, and hope that there is no change in the new SailfishOS release which breaks the SailfishOS:Chum GUI application; if there is, please report that soon at [the SailfishOS:Chum GUI application's issue tracker](https://github.com/sailfishos-chum/sailfishos-chum-gui/issues).
* Disclaimer: The SailfishOS:Chum GUI application and its installer may still have flaws, kill your kittens or break your SailfishOS installation! Although this is very unlikely after years of testing by many users, new flaws may be introduced in any release (as for any software). Mind that the license you implicitly accept by using the SailfishOS:Chum GUI application or the SailfishOS:Chum GUI Installer excludes any liability.


### Installation instructions

* Initial installation without having Storeman installed
1. Enable "System → Security → Untrusted software → Allow untrusted software" in the SailfishOS Settings app.
2. Download the current SailfishOS:Chum GUI Installer RPM from [its "latest release" page at GitHub](https://github.com/storeman-developers/harbour-storeman-installer/releases/latest), [OpenRepos.net](https://openrepos.net/content/olf/sailfishos-chum-gui-installer) or [the SailfishOS:Chum repository](https://build.merproject.org/project/show/sailfishos:chum/sailfishos-chum-gui-installer).
3. Tap on the "File downloaded" notification on your SailfishOS device or select the downloaded RPM file in a file-manager app and choose "Install" in its pulley menu; then confirm the installation.
4. Preferably disable "Allow untrusted software" again.

* Installation via Storeman
* **Installation via Storeman**
1. Search for *Installer*.
2. Select the *SailfishOS:Chum GUI Installer* by *olf*.
3. Enable olf's repository in the top pulley menu.
4. Install *SailfishOS:Chum GUI Installer*.

* **Initial installation without having Storeman installed**
1. Enable "System → Security → Untrusted software → Allow untrusted software" in the SailfishOS Settings app.
2. Download the current SailfishOS:Chum GUI Installer RPM from its ["latest release" page at GitHub](https://github.com/storeman-developers/harbour-storeman-installer/releases/latest), [OpenRepos.net](https://openrepos.net/content/olf/sailfishos-chum-gui-installer) or the [SailfishOS:Chum repository](https://build.merproject.org/project/show/sailfishos:chum/sailfishos-chum-gui-installer).
3. Tap on the "File downloaded" notification on your SailfishOS device or select the downloaded RPM file in a file-manager app and choose "Install" in its pulley menu; then confirm the installation.
4. Preferably disable "Allow untrusted software" again.

### Features of SailfishOS:Chum GUI Installer

* SailfishOS:Chum GUI Installer creates a persistent log file `/var/log/sailfishos-chum-gui-installer.log.txt`.
* SailfishOS:Chum GUI Installer runs "unattended": I.e., without any manual steps, after its installation has been triggered, until the SailfishOS:Chum GUI application is installed.
* SailfishOS:Chum GUI Installer is slow, because it calls `pkcon` three times, which acts quite slowly. The minimal run time for SailfishOS:Chum GUI Installer is about 7 seconds, the typical run time is rather 10 seconds (measured from the moment SailfishOS:Chum GUI Installer's installation has been triggered, until ultimately the SailfishOS:Chum GUI application is installed). This is already a lot, but I rarely experienced a stalled Packagekit daemon (for which `pkcon` is just a command line frontend, communicating with the daemon via D-Bus) during heavy testing, which can be observed with the crude `pkmon` utility (`Ctrl-C` gets you out.:smiley:), so SailfishOS:Chum GUI Installer tries to detect these "hangs" and to counter them: If that happens, its run time can be up to slightly more than 1 minute. In the worst case a stalled PackageKit daemon (and with it its `pkcon` client process(es)) stalls SailfishOS:Chum GUI Installer, until the PackageKit daemon reaches its idle time out of 300 seconds (5 minutes; this could theoretically happen three times, resulting in a likely unsuccessful run time of more than 15 minutes).
* SailfishOS:Chum GUI Installer is slow, because it calls `pkcon` three times, which acts quite slowly. The minimal run time for SailfishOS:Chum GUI Installer is about 7 seconds, the typical run time is rather 10 seconds (measured from the moment SailfishOS:Chum GUI Installer's installation is triggered, until the SailfishOS:Chum GUI application is installed and its icon is displayed at the "launcher"). This is already a lot, but I rarely experienced a stalled Packagekit daemon (`packagekitd`, for which `pkcon` is just a command line frontend, communicating with the daemon via D-Bus) during heavy testing, which can be observed with the crude `pkmon` utility (`Ctrl-C` gets you out.:smiley:), so the SailfishOS:Chum GUI Installer tries to detect these "hangs" and to counter them: If that happens, its run time can be up to slightly more than 1 minute. In the worst case a stalled PackageKit daemon (and with it its `pkcon` client process(es)) stalls SailfishOS:Chum GUI Installer, until the PackageKit daemon reaches its idle time out of 300 seconds (5 minutes; this could theoretically happen three times, resulting in a likely unsuccessful run time of more than 15 minutes).
5 changes: 5 additions & 0 deletions bin/sailfishos-chum-gui-installer
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,11 @@ then systemd-cat -t "$called" -p 6 printf "%s\n" "$logentry"
else systemd-cat -t "$called" -p 4 printf "%s\n" "[Warning] PID $mypid failed to write to $logfile"
fi

# Log some status data:
printf "\n%s" 'From /etc/os-release: '; source /etc/os-release; printf "%s\n" "$ID $VERSION_ID $SAILFISH_FLAVOUR"
printf "\n%s\n" 'Output of `ssu status`, UID omitted:'; ssu s | fgrep -iv 'UID:'
printf "\n%s\n" '"chum" entries from `ssu lr`:'; ssu lr | fgrep chum | tr -s ' '

# Provide RPM with a little time to proceed finishing the RPM transaction,
# which called this script asynchronously, because pkcon might fail
# enqueuing a pkcon-job while this RPM transaction is unfinished.
Expand Down
2 changes: 1 addition & 1 deletion rpm/sailfishos-chum-gui-installer.spec
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Name: sailfishos-chum-gui-installer
# natural number greater or equal to 1, which may be prefixed with one of
# {alpha,beta,rc,release} (e.g., "beta3"). For details and reasons, see
# https://github.com/storeman-developers/harbour-storeman-installer/wiki/Git-tag-format
Version: 0.3.1
Version: 0.3.2
Release: 1
Group: Applications/System
URL: https://github.com/sailfishos-chum/%{name}
Expand Down

0 comments on commit f631841

Please sign in to comment.