Update documentation

[nephros]

Implement some if the things mentioned in Issue #87

#78

[Olf0]

Looking O.K., but needs another review (because I changed a lot); please read issue #78 first.

Also: Which other "archive files" (name formats!?!) in line 18?

[nephros]

Also: Which other "archive files" (name formats!?!) in line 18?

In theory any patch dev can distribute their patches just by giving out download links to archive files in any format they choose, be that .zip, .rar, whatever MacOS uses these days, or LHA if they run an Amiga.
No need to use Web Catalog, RPM or OpenRepos, and no technical reason to use .tar.gz or .zip.

[b100dian]

big 👍

[Olf0]

Resolved merge conflicts and added an additional line denoting @nephros' research results: #73 (comment)

I am not really happy about https://github.com/sailfishos-patches/patchmanager/pull/81/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R56
because one aim is to consolidate the available information here at Github. But as long as there is additional, valuable information at https://coderus.openrepos.net/pm2/usage/ , it sure has to be mentioned.

[Olf0]

@nephros, did I correctly add a trailing comma in line 7: https://github.com/sailfishos-patches/patchmanager/pull/81/files#diff-4e19fb89ae9a5a8f061f2ccba71814601d00d625a7f836333b1c983a11d953fcR7 ?

[Olf0]

Also: Which other "archive files" (name formats!?!) in line 18?

In theory any patch dev can distribute their patches just by giving out download links to archive files in any format they choose, be that .zip, .rar, whatever MacOS uses these days, or LHA if they run an Amiga. No need to use Web Catalog, RPM or OpenRepos, and no technical reason to use .tar.gz or .zip.

But some mechanism must unpack these, right? So how would a LHA archive be unpacked on SailfishOS?
Some information or understanding on my side is missing here.
I assume that only a specific set of archive formats is currently working.

[nephros]

@nephros, did I correctly add a trailing comma in line 7: https://github.com/sailfishos-patches/patchmanager/pull/81/files#diff-4e19fb89ae9a5a8f061f2ccba71814601d00d625a7f836333b1c983a11d953fcR7 ?

Absolutely! Good catch, I spotted two or three others now. Fixed.

[nephros]

Also: Which other "archive files" (name formats!?!) in line 18?

In theory any patch dev can distribute their patches just by giving out download links to archive files in any format they choose, be that .zip, .rar, whatever MacOS uses these days, or LHA if they run an Amiga. No need to use Web Catalog, RPM or OpenRepos, and no technical reason to use .tar.gz or .zip.

But some mechanism must unpack these, right? So how would a LHA archive be unpacked o SailfishOS? Some information or understanding on my side is missing here. I assume that only a specific set of archive formats is currently working.

Hmm, now that you mention it, I might try to get an LHA unarchiver published at Chum ;)

This is getting a bit theoretical - all I mean is we can't know how users get patches on their systems, or how devs distribute them. They might be using have some weird workflow of getting archives per mail, unpacking on a mac, putting on OneDrive, copying on the device from OneDrive to the patch dirs or whatever.
And we don't need to care, we just want the correct files in the correct location in the end.

So that's why I added "RPM or other archive" - they can do what they want, but the must know what to include and what not.

[nephros]

I am not really happy about https://github.com/sailfishos-patches/patchmanager/pull/81/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R56 because one aim is to consolidate the available information here at Github.

Well one step is done: we have now our own .spec example do we can remove the link to the coderus package (which uses an outdated .spec anyway, it's from ausmt times).

[Olf0]

I am not really happy about https://github.com/sailfishos-patches/patchmanager/pull/81/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R56 because one aim is to consolidate the available information here at Github.

That was rather a kind of "just saying".

Well one step is done: we have now our own .spec example do we can remove the link to the coderus package (which uses an outdated .spec anyway, it's from ausmt times).

Well, then do it and merge "step one"! 😁

[b100dian]

Ah! why did I think this was already merged:) Thanks! it was in the changelog:P

[Olf0]

Ah! why did I think this was already merged:) Thanks! it was in the changelog:P

No, I wasn't and I originally intended to wait for @nephros to do that.
But then I thought, we should really get this in, also because I wanted to add stuff on top of it (and not even more to it).

[Olf0]

I now also deleted this (merged -> stale) branch, because I already merged stuff on top of it in master.

[b100dian]

Ok, I just set this to true

After pull requests are merged, you can have head branches deleted automatically.

[Olf0]

Ok, I just set this to true

After pull requests are merged, you can have head branches deleted automatically.

I do not like that, because sometimes there are reasons for keeping a merged branch a little. Automatisms can turn against you!

Please set it back to its original setting.

BTW, I wanted to add an issue template, but apparently I cannot (supposedly due to missing rights).
Hence the usual, "Either you do it or provide me with the rights to do it".

REPRODUCIBILITY (% or how often):
BUILD ID = OS VERSION (Settings > About product):
PATCHMANAGER VERSION (Settings > Patchmanager > About):
REGRESSION: (compared to previous release: Yes, No, ?):

DESCRIPTION:

PRECONDITIONS:

STEPS TO REPRODUCE:

EXPECTED RESULT:

ACTUAL RESULT:

ADDITIONAL INFORMATION:

(Please ALWAYS attach relevant data such as logs, screenshots etc.)

[b100dian]

Either you do it or provide me with the rights to do it

This is a good discussion to have.
My feeling right now is that I am "an elephant in a china shop" because I have got admin rights to this org and the transifex one.
Therefore, before I get comfortable with all the things I could break, I would like to remain a single elephant (not three:) and discuss changes like this.
I am more like a paper pusher in this role and will try to apply the "2 out of 3" rule we got in w.r.t pull request merging[1] to most kinds of changes.
Same goes for transifex, where I applied the membership to zn you requested.

In this specific case, I don't currently think an issue template will help ourselves (as I've already added note-to-self bugs and you folks added all kinds of scratch-an-itch issues) and since we're not invaded with "unable to reproduce" bugs, i don't think it will help users. If @nephros considers an issue template will help I will make a PR with it

I do not like that, because sometimes there are reasons for keeping a merged branch a little.

There's a restore button.

[1] "2 out of 3" <=> one author + one reviewer => merge

[Olf0]

This is a good discussion to have.
My feeling right now is that I am "an elephant in a china store" because I have got admin rights to this org and the transifex one.
Therefore, before I get comfortable with all the things I could break, I would like to remain a single elephant (not three:) and discuss changes like this.

Yes, let us have this discussion. Originally I intended to open a new discussion thread for this, but simply continuing here is fine for me.

I am also glad, that you seem to be receptive to open (and from my side always clear, sometimes bordering "harsh") statements.

I cannot concur, for a couple of reasons, which fall into two categories:
practical and social aspects

Under the social aspects, I can tell that it felt strange that my repeated offer to Andrey to take care and responsibility for this Github repo and the Transifex repo (explicitly including to responsibly distribute administrative rights) was met with absolute silence, but ultimately you received administrator rights for both after triggering him via Telegram. I do not know and stopped to care what his considerations were; except if he instructed you to be restrictive with sharing administrative rights (i.e., please state if he wanted that).

Nevertheless, this creates a situation, in which we are not a team of peers (i.e., "on a par" / on equal level; which does not mean "be equal", because everyone has different strengths). E.g., I have to ask you (as I already did a couple of times), if you transfer the necessary rights to me to perform an action or perform the action by yourself.
Specifically assuming the "paper pusher" role means that you are the only one to judge and to ultimately decide. The same goes for your statement that you prefer to be the only "Elephant" who has the ability to break things. This is basically self-assigning the project leader role.
While that clearly puts @nephros and me in a subordinate role, my primary concern is why you apparently expect him and me not to alter settings and to perform administrative work as carefully as you do?

Furthermore this is a consideration I really cannot follow, as it was rather me questioning the need and suggesting a conservative / conservational approach to all significant or disruptive changes (e.g. deleting branches) plus double checking that such actions do not discard anything which might be of value (even if that is just for keeping history documented).
And I cannot see that any action by @nephros or me indicated, that one of us may not responsibly and carefully handle administrative powers.
If you perceive one of these two points differently, I would really like to know that and what triggered that perception.

Under practical aspects this approach does not make any sense to me:

• It creates extra work and delays, because @nephros and I simply cannot perform some tasks, as e.g. inviting or accepting new translators at Transifex. Instead we have to ask you to do that. This feels awkward in a team of volunteers, creates the additional work to explicitly ask each time and increases your workload with administrative stuff.
• You have become a single point of failure: I.e., in case something unfortunate happens (illness, accident etc. or even just "severely out of time") nobody else has the administrative rights to fully substitute you.
  Exactly this consideration is the reason why I asked for a secure communication channel to share the password for the "Patchmanager" account at Openrepos.

---

For the original trigger of this, the issue template:
It was freshly created (for FSO), simply creates a pre-filled page when opening a new issue (no one is forced to use it, as it can be freely altered, including deleting it completely per <Ctrl-A> & <Del>) and such guidance for external bug reporters has shown to greatly enhance the quality of bug reports at many projects.
Just take a look at old, closed issues: Many lack the most basic information as Patchmanager version and SailfishOS version.
Hence I cannot (and do not) really believe that this is questionable under practical aspects.

[b100dian]

I'm more interested in discussing the social aspects. The practical aspects are, well, only practical.

I have read everything you have written, I'm just anchoring the comments to some quote but they should respond to the whole paragraph.

it felt strange that my repeated offer to Andrey (...) was met with absolute silence

I don't know the reasons behind this. Maybe it's short messages, maybe the medium (IM).

I considered it very important to not ping a person that just left with many messages.
I've only written to him 3 times in this respect (repo maintainer as you got now, admin access when default branch needed change, statement on license.).

except if he instructed you to be restrictive with sharing administrative rights

He did not, I just feel [obliged/the pressure] (hence the elephant quote) to not act quickly.

Nevertheless, this creates a situation, in which we are not a team of peers

I am not comfortable in this position either.

why you apparently expect him and me not to alter settings and to perform administrative work as carefully as you do?

My intuition says that a single person with admin rights is going to generate discussions, while multiple persons with admin rights may generate frustration. But let's try.

For the original trigger of this, the issue template

See? let's discuss it first.

For the other changes I applied: github actions came gratis with merging sfos4-fix. Merging PRs with only with reviews was meant as a team thing. Deleting branches on merge was something I thought you would appreciate (it sounded like you need that) so, agreeing, I said it's 2/3 rule.

[b100dian]

I've created patchmanager-admins group. Do you see the whole settings now @Olf0 and @nephros ?
I've also added Peter on transifex as Project Maintainer. I will upgrade you both to Organization level when I found where that is (DONE).

BTW, we should probably release those ~4 translation updates.

[Olf0]

I've created patchmanager-admins group. Do you see the whole settings now @Olf0 and @nephros ?

Yes, I do: Thanks.

I've also added Peter on transifex as Project Maintainer. I will upgrade you both to Organization level when I found where that is (DONE).

BTW, we should probably release those ~4 translation updates.

I still have to check the remaining changes from PR #46, now that I may be able to do that WRT access rights.

Please slow down, 4 translation updates are not sufficient new material to trigger a new release IMO. Usually there should be at least a bug fix or some functional enhancement or change.
Maybe having carried out all these maintenance tasks would suffice:

• Getting the whole translations stuff in order and having checked that.
• Update donations page.
• Eliminate the choppy scrolling of the About page (with or without the easter-egg).

[Olf0]

Deleting branches on merge was something I thought you would appreciate (it sounded like you need that) so, agreeing, I said it's 2/3 rule.

Well, I hardly can express clearer than that, that I neither "need" or want it:

I do not like that, [...] Automatisms can turn against you!
Please set it back to its original setting.

@nephros, we do need your opinion on the "autodelete branch after merging" function!

---

@nephros, we also need your opinion on the topic issue template.

• I suggested one here, which is the one used at FSO.
• @b100dian argued against it:

  In this specific case, I don't currently think an issue template will help ourselves (as I've already added note-to-self bugs and you folks added all kinds of scratch-an-itch issues) and since we're not invaded with "unable to reproduce" bugs, i don't think it will help users.

• I argued for it:

  It was freshly created (for FSO), simply creates a pre-filled page when opening a new issue (no one is forced to use it, as it can be freely altered, including deleting it completely per <Ctrl-A> & <Del>) and such guidance for external bug reporters has shown to greatly enhance the quality of bug reports at many projects.
  Just take a look at old, closed issues: Many lack the most basic information as Patchmanager version and SailfishOS version.
  Hence I cannot (and do not) really believe that this is questionable under practical aspects.

---

I think we should also establish another rule, covering the case when we do not have an odd number of opinions: Stick to the default setting (because that is usually reasonable).

Opinions on this?

Specifically for the open points here: If @nephros does not voice an opinion, this would result in no autodelete of branches and no issue template.

[nephros]

Deleting branches on merge was something I thought you would appreciate (it sounded like you need that) so, agreeing, I said it's 2/3 rule.

Well, I hardly can express clearer than that, that I neither "need" or want it:

I do not like that, [...] Automatisms can turn against you!
Please set it back to its original setting.

@nephros, we do need your opinion on the "autodelete branch after merging" function!

Well, it has come to this - a dilemma. Time to make one enemy then.

I have all branches in my local git repo(s), and use the GitHub web interface as little as possible, I have no quarrels with autodelete-after merge on GitHub forks.

So for that.

[nephros]

Seeing how inconsistent in quality bug reports are also on FSO despite the template, I also don't think it will greatly help good reports. The only thing that helps there is a real guided issue reporting tool, and a human first level team to hunt for complete information.

Also, the template on FSO isn't very good, people understand the different fields differently, some delete the pre-filled stuff, others don't and so on. To me that's even more annoying than a free form report.

But still, a common format helps a bug wrangler in quickly skimming for relevant information. So I vote for a template as long as it's simple. So going from what was already proposed, my stripped-down version:

REPRODUCIBILITY (% or how often):
SailfishOS VERSION (Settings > About product):
PATCHMANAGER VERSION (Settings > Patchmanager > About):
REGRESSION: (compared to previous release: Yes, No, ?):

DESCRIPTION:

#### PRECONDITIONS:

STEPS TO REPRODUCE:

#### EXPECTED RESULT:
#### ACTUAL RESULT:

ADDITIONAL INFORMATION:

(Please ALWAYS attach relevant data such as logs, screenshots etc.)

[Olf0]

Well, it has come to this - a dilemma.

Oh, it regularly will, due to the "2of3" rule. Get used to it! 😜
(Hell will break loose, if we ever are an even number of active contributors.)
(I also wonder, if the "2of3" rule addresses a simple majority or a qualified one with a 66% quorum; although that currently does not matter at all.)

Time to make one enemy then.

Though you may utilise a trick: Be the first or second to state an opinion. 😉

• So "autodeleting merged branches" stays.
• And we're going to have an issue template.
  I am actually glad that you streamlined it a bit, I consider to use that at FSO, too.
  Note that my version already improved upon Jolla's original (which appears to be written in less than 5 minutes without any quality assurance by some other sailor, but that impression is nothing new, sadly for much code, too) in a couple of aspects.
  I currently read in some thread at FSO that many seem to fail to understand what a "regression" is, so it absolutely makes sense to delete that as a mandatory field. But I want to retain a hint to consider, if this is a regression and if it is well reproducible etc., hence I put that in the last line in brackets (but deleted that idiotic, all-caps "ALWAYS" there).
  Can you both please review this version: I love criticism (to make things better), as long as it is not ad hominem.

SailfishOS VERSION (Settings > About product):
PATCHMANAGER VERSION (Settings > Patchmanager > About):

BUG DESCRIPTION

STEPS TO REPRODUCE

ADDITIONAL INFORMATION

(Please consider which other pieces of information may be relevant, e.g. denote if this is not always reproducible, if it is a regression, attach relevant data such as log files or the systemd journal, provide screenshots etc.)

[b100dian]

Let's make a Decisions discussion. But then again, let's discuss where the topics are.

I have no quarrels with autodelete-after merge on GitHub forks.

It can delete your fork's branches too.

The positions about this feature are like:

• I'm ok with it, I turned it on because I thought @Olf0 wanted.
• @Olf0 is actually againsts it:)
• @nephros is ok with it

I think this is a case where we can turn it off per Olf's opposing. Sorry for the misinterpretation.

And we're going to have an issue template.

Looks better indeed. When you use the feature on github, it should just create a Pull Request, so we can comment there too.

In general, I think I've overly simplified with 2/3 rule. Consider it "let's discuss it" rule.

[Olf0]

Let's make a Decisions discussion. But then again, let's discuss where the topics are.

I have no quarrels with autodelete-after merge on GitHub forks.

It can delete your fork's branches too.

The positions about this feature are like:

* I'm ok with it, I turned it on because I thought @Olf0 wanted.

* @Olf0 is actually againsts it:)

* @nephros is ok with it

I think this is a case where we can turn it off per Olf's opposing. Sorry for the misinterpretation.

Well, I just wanted to cleary denote, that this is not "for me".
I am only weakly against it. I just do not like automatisms, especially the ones which delete something.
And while such branches usually will not be needed any longer, I have no idea how long they can be restored.

You may leave it as it currently is (autodeleting).

And we're going to have an issue template.

Looks better indeed. When you use the feature on github, it should just create a Pull Request, so we can comment there too.

It is just a MarkDown file: https://github.com/sailfishos-patches/patchmanager/pull/107/files

And ususally a freshly filed issue does not (immediately) result in a Pull Request. IMO they shall not be that strongly connected.

[roman-neuhauser]

Ok, I just set this to true

After pull requests are merged, you can have head branches deleted automatically.

I do not like that, because sometimes there are reasons for keeping a merged branch a little. Automatisms can turn against you!

Hello guys,

I hope you don't mind me chiming in from the sidelines.

First, being a data hoarder myself, I share @Olf0's instinct, but the branches get deleted only after a merge and thus no commits are lost. Given this, I believe @Olf0 should name some of the reasons for keeping merged branches around. The remark

I have no idea how long [branches] can be restored

seems to betray some kind of misunderstanding of the branch concept in Git: @Olf0's concerns might be unfounded. A git branch is just a label attached to a commit and can be "restored" at any time:

git branch $name $hash

is all it takes and there's no clock ticking.

Second, I believe that a canonical repo which receives contributions from multiple developers and strives for openness like sailfishos-patches/patchmanager, should not receive direct pushes from contributors. See, if you guys push your branches into this repository, you'll either have to let every J. Radom Hacker do the same, or you'll have a very two-tier development group. If I had some changes for patchmanager today, I'd have to submit them as a pull request from roman-neuhauser/patchmanager:some-branch -- and that's perfectly fine! It doesn't require any privileges on my part, it's open, and it scales to any number of contributors. Not to mention the potential for naming conflicts when multiple people push feature branches into the canonical repo: it's asking for one person to obliterate another's work. All it takes is two branches named something like doc-update and a blip of less-than-100% concentration.

Third, avoiding feature branches in the canonical repo also scratches @Olf0's itch: the source branch can remain in the source repository for as long as the originator desires. And if a member of the team wants to keep copies of feature branches authored by the rest of the team, it's just a git remote add / git remote update away.

[nephros]

Thanks for your insights!

Very good point about feature branches in the main repo. I shall do the fork-push-pr method from now on for the small things and leave branching for the larger stuff.

[Olf0]

First, being a data hoarder myself, I share @Olf0's instinct, but the branches get deleted only after a merge and thus no commits are lost. Given this, I believe @Olf0 should name some of the reasons for keeping merged branches around. The remark

I have no idea how long [branches] can be restored

seems to betray some kind of misunderstanding of the branch concept in Git: @Olf0's concerns might be unfounded. A git branch is just a label attached to a commit and can be "restored" at any time:

git branch $name $hash

is all it takes and there's no clock ticking.

And where do the content of $name and $hash come from?

Look, this discussion is primarily about Github's webfrontend, so my statement "I have no idea how long [branches] can be restored" was meant to address only that. IIRC this option there ("Restore branch") vanishes after some time.

It is about:

• Responsibility: IMO someone (usually the creator of that branch) should actively delete that branch as a consciously taken last step after merging.
• Choice: For more complex Pull requests, I like to keep the corresponding branch for a few days or weeks, just in case something should arise for which comparing, copying&pasting etc. at the web-frontend comes handy.
• Convenience: For all tasks which can be handled at the web-fontend, I do like to handle them there and want to keep this possibility open for others.

BTW, it is not about "being a data hoarder", because these temporary branches shall be deleted some time after merging; but IMO preferably not automatically and immediately.

Second, I believe that a canonical repo which receives contributions from multiple developers and strives for openness like sailfishos-patches/patchmanager, should not receive direct pushes from contributors. See, if you guys push your branches into this repository, you'll either have to let every J. Radom Hacker do the same, or you'll have a very two-tier development group. If I had some changes for patchmanager today, I'd have to submit them as a pull request from roman-neuhauser/patchmanager:some-branch -- and that's perfectly fine! It doesn't require any privileges on my part, it's open, and it scales to any number of contributors. Not to mention the potential for naming conflicts when multiple people push feature branches into the canonical repo: it's asking for one person to obliterate another's work. All it takes is two branches named something like doc-update and a blip of less-than-100% concentration.

1. I do not think there is anything wrong with a "two-tier development group" (why the "very"?!?), i.e. having a "core team" of developers proven to act responsibly and to back this project in the long run. IMO it is rather a natural setup, and it was a long way to create a team with shared responsibilities and mutual trust.
   I do not see any reason why "open to contributions" shall mean "everybody contributes the same way", and actually no advantages from such an approach, but some disadvantages.
   I also cannot see why our current workflow "does not scale" and why it would have to (it is only the core team members), and branch naming conflicts never occurred and are easily avoided by using GitHub's web-frontend.
   Plus it would not alleviate any of my aforementioned points of the "autodelete function", even though you seem to think otherwise.

2. But it would make close collaboration in the core team harder, especially when reviewing Pull Requests: This way one can simply add commits to that branch.
   Just to anticipate you may reply that there are settings, which enable this for branches in private repos (e.g. "allow for commits from maintainers" at the web-frontend): They have to be deliberately set and I do not like (just a gut feeling) to alter the content of others people's repos.
   Again, I cannot see any advantage, but do see disadvantages for us using such a setup.

Your line of thinking seems to be very technical, assuming everyone uses git primarily at the command line and includes other assumptions which are not relevant (e.g., there are many contributors outside of the core team; we still have to see the first and in the past they were very rare).

Last but not least, this point ("autodeleting merged branches") was basically settled among the core team: Nobody has a strong opinion, but the majority likes it.
So I do not think it is necessary to discuss that further (and leave it switched on), unless relevant, new aspects arise.

[Olf0]

BTW, I also aligned the templates at

• https://forum.sailfishos.org/t/bugs-in-patchmanger-3-1-0/8552/2
• https://forum.sailfishos.org/t/bugs-in-patches-for-patchmanager/8553/2

to our final result #81 (comment), which ultimately was filed at
https://github.com/sailfishos-patches/patchmanager/blob/master/.github/ISSUE_TEMPLATE/patchmanager-issue-template.md

[Olf0]

BTW @b100dian, I was able to address your concerns WRT an issue template:

In this specific case, I don't currently think an issue template will help ourselves (as I've already added note-to-self bugs and you folks added all kinds of scratch-an-itch issues) and since we're not invaded with "unable to reproduce" bugs, i don't think it will help users.

Because I did not set a default template, but just created a template in /.github/ISSUE_TEMPLATE/, a new issue is not pre-filled with the template: Instead one chooses between an empty issue (as usual) or the template(s) as a first step when creating a new issue.

The issue template mechanism is a GH functionality, which turned out to be surprisingly nice: Simple and mighty at the same time, multiple different, templates can be offered and pre-filling new issues with one is optional.