Enhance documentation for analysing bugs

[Olf0]

Enhance documentation for analysing bugs.

There were a couple of mini-guides by Andrey, especially how to properly filter the systemd journal. But IIRC a few variants exists, and they have to be re-searched at the PM-thread at TMO, the comments at Openrepos, at TJC etc.

Then these variants should be condensed into a single, optimal one, if possible.

[Olf0]

Well, https://forum.sailfishos.org/t/bugs-in-patches-for-patchmanager/8553/14 and https://forum.sailfishos.org/t/bugs-in-patches-for-patchmanager/8553/15 ff. are additional pieces for this, but in line with issue #85 I think we shall not add even more locations, where such documentation is spread.
Luckily (just checked) TJC has little to offer, but this enormous thread at TMO contains "all the historic info" (and completely unstructured, in almost 3000 messages): https://talk.maemo.org/showthread.php?t=92935
Additionally there is some relevant info (likely duplicated in the TMO thread) in the much fewer comments pages at Openrepos: https://openrepos.net/content/coderus/patchmanager-30

Furthermore, we shall clearly differentiate between "Bugs in Patchmanager" and "Issues with Patches for Patchmanager", plus also separate interfacing noobs (at FSO) and Linux / tech savvy users (here at Github). (IMO, we already reached consensus on that.)
Otherwise we will structurally recreate the aforementioned TMO thread: a huge, unstructured pile / mess where everybody posts everything which is somehow related to Patchmanager and its patches!
In this regard, I am not really happy with the aforementioned two postings at FSO: While the first one fits perfectly to the category "Issues with Patches for Patchmanager" and the content of both is technically absolutely fine (and well written), they are unsuitable for noobs (who should stubbornly fill out the form) and the second one is primarily about Patchmanager (not patches for it). It is also obvious, that a single forum thread is unsuitable for structuring information, as the TMO PM-thread has well proven.

Thinking about this for a while now, I believe the Wiki here is most suitable place to gather such technical information / documentation in a structured and maintainable manner.
Maybe we should start to streamline the Readme and move anything more detailed to the Wiki, starting to build some basic structure (a fundamental page hierarchy) there.
@nephros, what do you think?
And please excuse my criticism, your posts are really nice, just IMO not at an appropriate place, especially when I extrapolate how this FSO thread might look like in one or two years. Also mind that the ability to alter (i.e., correct, enhance etc.) posts at FSO ceases after a while.

[Olf0]

Just checked all comments at Openrepos for PM3.0, these are the only three relevant places with information there:

• WRT translations, PM's environment variable and logging:
  Three different sections of the description at https://openrepos.net/content/coderus/patchmanager-30
• Logging variant 2: https://openrepos.net/comment/25667#comment-25667
• Logging variant 3: https://openrepos.net/comment/25666#comment-25666

[nephros]

It's the nature of forums and forum threads that they become unwieldy over time - I don't think anything can be done about that apart from not having them at all.

Still, it's good to be visible that way on FSO.

I agree that re-usable information should be in a more stable place - a Wiki is sounds like a good idea, or maybe a collection of .md files in a docs subdir in the code? I am not familiar with how Github stores wiki information, is it actually stored in the repo or separately?

That being said, I object to separating users into "noobs" and "savvy" people. As long as feedback isn't overwhelming, and it is not at the current pace, I don't think bug/report/feedback triaging is that much of an issue.

About my posts: I agree but at the time it seemed the best place, and I like to engage complaints quickly. If an answer is useful it can quell similar reports if people read (which they don't) or search (which they also don't).

So yeah, all for a wiki-type thing, and collecting information from those sources there.

It will be a convenient thing to link to in whatever communication about issues happens.

[Olf0]

It's the nature of forums and forum threads that they become unwieldy over time

That is why I try / think we should try to avoid using a forum (-thread) for receiving bug reports.
But you and Vlad correctly pointed out that FSO is where most SFOS-users have an account, hence convincing me that we should be at least present there for receiving bug reports: This is why I created those two threads.

• I don't think anything can be done about that apart from not having them at all.

IMO, this is too strictly black and white thinking!
I believe we should try to steer people away from FSO for anything more complex than filling out the form and clarifying simple things. This is the only reason why I differentiated between "noobs" (meaning: people unable to file an issue at Github) and more "tech savvy" users (i.e., people who are able to do so).

Still, it's good to be visible that way on FSO.

I would agree, if that sentence was without "that way", because I am not sure what that is meant to imply.

I agree that re-usable information should be in a more stable place - a Wiki is sounds like a good idea, or maybe a collection of .md files in a docs subdir in the code?

A wiki at Github is exactly that, but in a separate repository, see https://github.com/sailfishos-patches/patchmanager/wiki

I am not familiar with how Github stores wiki information, is it actually stored in the repo or separately?

The Github webfrontend also does not support branches for that wiki repo, hence we should first backup what is there and transfer it into a new top-level directory (e.g., .wiki-backup) in the legacy branch of the code repository.
I would be glad, if you do that, because I rarely use git at the command line and have no idea how to properly merge the content including its history of the two repos (with git-fetch or git-merge; maybe that is even feasible by a simple git-pull or git-rebase applied in the right way?). Well AFAIU thinking in "content" is always wrong for git, it is only "commits at specific points in time" (the sum of which are "history").
The link to clone the Patchmanager's wiki repo is (according to GH) https://github.com/sailfishos-patches/patchmanager.wiki.git

That being said, I object to separating users into "noobs" and "savvy" people.

Why?
See above for my reasons to differentiate, which are triggered by trying to find a way "to keep the FSO bug threads manageable in the long run".

As long as feedback isn't overwhelming, and it is not at the current pace, I don't think bug/report/feedback triaging is that much of an issue.

My concerns are not about "triaging", they are about manageability, i.e. not creating such a forum thread monster as the PM-thread@TMO. Plus avoiding the typical approach, "if that happens, just discard it and start anew", which simply recreates the same structural flaws and leads to the same result. Said in a different way: We should learn from the obvious result of Andrey stating "please file all PM-related questions there" (and how wrong a FSO "feels" for reporting and discussing bugs, if one is used to a proper issue tracker).

About my posts: I agree but at the time it seemed the best place, and I like to engage complaints quickly.

I fully understand that and that could have been me.

If an answer is useful it can quell similar reports if people read (which they don't) or search (which they also don't).

Bingo! 😞

So yeah, all for a wiki-type thing, and collecting information from those sources there.

👍

It will be a convenient thing to link to in whatever communication about issues happens.

That is exactly my goal: To be able to drop a link at FSO to some wiki content here, instead of writing this content there.

[Olf0]

@nephros, I would appreciate very much, if you perform:

The Github webfrontend also does not support branches for that wiki repo, hence we should first backup what is there and transfer it into a new top-level directory (e.g., .wiki-backup) in the legacy branch of the code repository.
I would be glad, if you do that, because I rarely use git at the command line and have no idea how to properly merge the content including its history of the two repos (with git-fetch or git-merge; maybe that is even feasible by a simple git-pull or git-rebase applied in the right way?). Well AFAIU thinking in "content" is always wrong for git, it is only "commits at specific points in time" (the sum of which are "history").
The link to clone the Patchmanager's wiki repo is (according to GH) https://github.com/sailfishos-patches/patchmanager.wiki.git

After that is done, I can wipe the wiki clean, then start building a new wiki structure and fill it by copying and adapting content from the aforementioned sources: PM3.0@Openrepos, PM-thread@TMO, README@here, your contributions at FSO etc.
When that is done, I would call for review / criticism / quality assurance / additions / enhancements.

[nephros]

@nephros, I would appreciate very much, if you perform:

The Github webfrontend also does not support branches for that wiki repo, hence we should first backup what is there and transfer it into a new top-level directory (e.g., .wiki-backup) in the legacy branch of the code repository.
I would be glad, if you do that, because I rarely use git at the command line and have no idea how to properly merge the content including its history of the two repos (with git-fetch or git-merge; maybe that is even feasible by a simple git-pull or git-rebase applied in the right way?). Well AFAIU thinking in "content" is always wrong for git, it is only "commits at specific points in time" (the sum of which are "history").
The link to clone the Patchmanager's wiki repo is (according to GH) https://github.com/sailfishos-patches/patchmanager.wiki.git

After that is done, I can wipe the wiki clean, then start building a new wiki structure and fill it by copying and adapting content from the aforementioned sources: PM3.0@Openrepos, PM-thread@TMO, README@here, your contributions at FSO etc. When that is done, I would call for review / criticism / quality assurance / additions / enhancements.

OK, done I think.

The old files are now in a branch called "historic" - but that branch is only visible in checked-out clones of the wiki repo, not on Github Web.

Anyway, I pushed a new, empty branch "master" which can now be used to make a new wiki structure.

[nephros]

Just as a note: https://github.com/ichthyosaurus/sailfish-patch is excellent for people to start developing patches, and should be integrated at some point in the wiki.

[Olf0]

@nephros, I would appreciate very much, if you perform:

The Github web-frontend also does not support branches for that wiki repo, hence we should first backup what is there and transfer it into a new top-level directory (e.g., .wiki-backup) in the legacy branch of the code repository.

OK, done I think.

The old files are now in a branch called "historic" - but that branch is only visible in checked-out clones of the wiki repo, not on Github Web.

Anyway, I pushed a new, empty branch "master" which can now be used to make a new wiki structure.

O.K., thanks.
Mmmh, I do not really like the fact, that the old content is fully hidden at the web-frontend, thus likely no one will find it any more. All in all the git GUI-handling for GH wikis is poor to broken, see https://github.com/sailfishos-patches/patchmanager/wiki/Home/_history and click on any of the commit hashes. 😞
When evaluating this, I briefly considered to create a hierarchy of Markdown documents in the code repository (a "hand made wiki"), because that eases the git handling a lot, but complicates other things and nobody not involved in this creation process will understand these considerations later (plus people will look for a wiki of a project at GH in its usual place).

Good to know that the old content is saved and safe, and I can start now to create a new wiki structure and content.
Still I would appreciate, if you reconsider to move the old content to a new top-level directory in the legacy branch at the code repository (as I originally suggested), so it can be found and accessed at the GH-GUI.

[Olf0]

@nephros, I wanted to determine, why https://github.com/sailfishos-patches/patchmanager/wiki/Home/_history only shows your commits and cloned the wiki repo locally.
But git branch --list only shows a single branch: master
And git log exactly shows the commits which are displayed at the GUI, nothing more. But IMO the master branch must have some older history (by Andrey).

Please carefully look in your local repo, if you do really have »The old files are now in a branch called "historic"«! Either I fail to see it (hope so), or it does not exist at GH.
Now the most important thing is to ensure, that the old content (preferably with its commit history) is saved and to make it publicly accessible again!
If you do have it locally, please first create a tar archive of the directory you cloned the wiki repo into. I would be glad, if you send me this archive per mail, then I will try to pursue my original plan (to move the old content with history to a new top-level directory in the legacy branch at the code repository) and enhance my git know-how. You might pursue your plan then: To push the "historic" branch into GH's wiki repo.

P.S.: The state at the oldest commit which still exists in the history of master does contain the old top level page, but the crucial "Patches list" sub-page (the real content, which ought to be saved) is missing, see https://github.com/sailfishos-patches/patchmanager/wiki/Home/e0c759729d831bae8dd3d311a1044d929a8d8ceb

[nephros]

@nephros, I wanted to determine, why https://github.com/sailfishos-patches/patchmanager/wiki/Home/_history only shows your commits and cloned the wiki repo locally. But git branch --list only shows a single branch: master And git log exactly shows the commits which are displayed at the GUI, nothing more. But IMO the master branch must have some older history (by Andrey).

Well that is consistent with what you quoted above. The GH web UI only shows the master branch content.

Please carefully look in your local repo, if you do really have »The old files are now in a branch called "historic"«! Either I fail to see it (hope so), or it does not exist at GH. Now the most important thing is to ensure, that the old content (preferably with its commit history) is saved and to make it publicly accessible again!

It is certainly there, both in my local copy and on GH. Try git branch -r you should see it, and can switch to it by git checkout historic - see below.

But I seem to have misunderstood your request. I thought the goal was a clean slate without the commit history, so that is what is there now.

If the goal is just to move the old pages somewhere and add other content, keeping all the history, I think we can do that simply on the original master branch.

If you do have it locally, please first create a tar archive of the directory you cloned the wiki repo into. I would be glad, if you send me this archive per mail, then I will try to pursue my original plan (to move the old content with history to a new top-level directory in the legacy branch at the code repository) and enhance my git know-how. You might pursue your plan then: To push the "historic" branch into GH's wiki repo.

Right, I can create a git bundle and send it per mail, but I don't think it' s really necessary, if you can check out the branch locally:

nemo@PGXperia10:~/git $ git clone git+ssh://github.com/sailfishos-patches/patchmanager.wiki.git wiki2
Cloning into 'wiki2'...
remote: Enumerating objects: 75, done.
remote: Counting objects: 100% (17/17), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 75 (delta 0), reused 12 (delta 0), pack-reused 58
Receiving objects: 100% (75/75), 10.18 KiB | 801.00 KiB/s, done.
Resolving deltas: 100% (17/17), done.
nemo@PGXperia10:~/git $ cd wiki2/
nemo@PGXperia10:~/git/wiki2 $ git branch
* master
nemo@PGXperia10:~/git/wiki2 $ git branch -r
  origin/HEAD -> origin/master
  origin/historic
  origin/master
nemo@PGXperia10:~/git/wiki2 $ git checkout historic
Branch 'historic' set up to track remote branch 'historic' from 'origin'.
Switched to a new branch 'historic'
nemo@PGXperia10:~/git/wiki2 $ git branch
* historic
  master
nemo@PGXperia10:~/git/wiki2 $ ls
Home.md          Patches-list.md
nemo@PGXperia10:~/git/wiki2 $ git switch master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.
nemo@PGXperia10:~/git/wiki2 $ ls
Home.md
nemo@PGXperia10:~/git/wiki2 $

In conclusion, I think we should undo the whole thing (especially as I kind of fumbled the "clean history" part of the new master branch, it has a lot of unnecessary commits right from the start) and simply do all changes on the old master branch, moving old stuff into _old or so and refer to it somehow from the new pages.
In fact I have done that in a new branch called new, please check it out ;) and let me know.

[Olf0]

@nephros, I wanted to determine, why https://github.com/sailfishos-patches/patchmanager/wiki/Home/_history only shows your commits and cloned the wiki repo locally. But git branch --list only shows a single branch: master
And git log exactly shows the commits which are displayed at the GUI, nothing more. But IMO the master branch must have some older history (by Andrey).

Well that is consistent with what you quoted above. The GH web UI only shows the master branch content.

Please carefully look in your local repo, if you do really have »The old files are now in a branch called "historic"«! Either I fail to see it (hope so), or it does not exist at GH. Now the most important thing is to ensure, that the old content (preferably with its commit history) is saved and to make it publicly accessible again!

It is certainly there, both in my local copy and on GH. Try git branch -r you should see it, and can switch to it by git checkout historic - see below.

Yes, I do see it now. I wonder why git branch --list does not show it, as it is supposed to list all branches. This is why I hate git at the command line (not because it is conceptually so different to the classic file based repos: That is fine and after a while I started to really like it.), many commands do not do what they do sound like.

But I seem to have misunderstood your request.

Yes. I wonder which of my words were so easy to fundamentally misunderstand:

The Github webfrontend also does not support branches for that wiki repo, hence we should first backup what is there and transfer it into a new top-level directory (e.g., .wiki-backup) in the legacy branch of the code repository.

I thought the goal was a clean slate without the commit history, so that is what is there now.

That is O.K., if though I did not mention anything like this.

If the goal is just to move the old pages somewhere and add other content, keeping all the history, I think we can do that simply on the original master branch.

Yes that was my original goal, plus making the old stuff visible somewhere (i.e., keeping it visible): That is why I suggested to move the old content with its history "into a new top-level directory (e.g., .wiki-backup) in the legacy branch of the code repository."

If you do have it locally, please first create a tar archive of the directory you cloned the wiki repo into. [...]
Right, I can create a git bundle and send it per mail, but I don't think it' s really necessary, if you can check out the branch locally:

Yes, that is unnecessary, now that I know I already have it.
(Although I doubt, that I can easily use it.)

In conclusion, I think we should undo the whole thing (especially as I kind of fumbled the "clean history" part of the new master branch, it has a lot of unnecessary commits right from the start) and simply do all changes on the old master branch, moving old stuff into _old or so and refer to it somehow from the new pages. In fact I have done that in a new branch called new, please check it out ;) and let me know.

Well that would also work. Although I do like it less than moving the old stuff somewhere else, because I reviewed it and know that we will never need anything of it: It is simply old cruft from the "legacy" timeframe (i.e., for Patchmanager 1 / early SailfishOS 1.1.x releases).
This is why moving it to a branch within the wiki repo would be perfect, if it would not be rendered invisible by the GH web-frontend then.
This is why I came up with my original suggestion, although I know that this means to merge the old wiki stuff into some new top-level directory of the lecacy branch (that is where / what it belongs to) of the code repository (to keep it visible).

[nephros]

Right, so in conclusion:

1. I'll copy the legacy Wiki files (old wiki master) as both a git bundle (which contains all the history) as well as as a copy of the current files into a wiki_archive directory in the code repo
2. Submit a PR against legacy branch with that
3. Restore the original wiki master branch
4. Delete the currently existing files from wiki, creating a commit which references the new location in the code repo legacy branch
5. You can continue working on the wiki and it will have the historic files there as well.

That sound like a plan?

[Olf0]

That sound like a plan?

Yes, absolutely the right plan from my POV.

[nephros]

Okay done.

See:

• https://github.com/sailfishos-patches/patchmanager/wiki/Home/_history
• archive the legacy wiki pages #146

[Olf0]

See:

• https://github.com/sailfishos-patches/patchmanager/wiki/Home/_history
• archive the legacy wiki pages #146

Both, the current wiki history and the archive of the old content in doc/wiki_archive/ of the legacy branch perfectly match and employ what I had in mind.
Thank you very much!

Now it is my turn to gather all the information and to structure and consolidate it in the new, empty wiki.
Note, that I will take my time for this, i.e., I plan to do this at a lower pace than you are pushing forth with the programming work.

[Olf0]

Just checked all comments at Openrepos for PM3.0, these are the only three relevant places with information there:

• WRT translations, PM's environment variable and logging:
  Three different sections of the description at https://openrepos.net/content/coderus/patchmanager-30
• Logging variant 2: https://openrepos.net/comment/25667#comment-25667
• Logging variant 3: https://openrepos.net/comment/25666#comment-25666

I was too slow in collecting this, Andrey disabled the comments, so variants 2 & 3 are gone.
@CODeRUS, IMO there is no reason to actively delete or hide old information. I would have been glad to be able to evaluate if this is still helpful.
Thus I would appreciate, if you switch the comments back on, at least for a while.

[nephros]

> Just checked _all_ comments at Openrepos for PM3.0, these are the only three relevant places with information there: > > * WRT translations, PM's environment variable and logging: > Three different sections of the description at https://openrepos.net/content/coderus/patchmanager-30 > * Logging variant 2: https://openrepos.net/comment/25667#comment-25667 > * Logging variant 3: https://openrepos.net/comment/25666#comment-25666 I was too slow in collecting this, @CODeRUS disabled the comments, so variants 2 & 3 are gone.

The Wayback Machine to the rescue! https://web.archive.org/web/20200922041227/https://openrepos.net/comment/25667

[Olf0]

Copy&Paste'd all extant fragments I could find into the corresponding Wiki pages at https://github.com/sailfishos-patches/patchmanager/wiki

Finished pages

• Environment variables

Unfinished pages

• Capturing logs
• Creating a Patch
• Debugging "64 bit issues"
• Debugging Patches
• Icons for Patches
• Ordering of Patches