Usage of issues

[kodebach]

I don't really no why we have this discussion, because we clearly disagree and won't come to an agreement, but @markus2330 started it in #4518.

Like everything, issues can be misused. We are currently writing too much text in issues and too little text in our repo. Of course it is also my fault, not having time to create PRs of what others write in issues (as I used to do). What you might misinterpret of me hating issues is me loving a beginner-friendly Elektra. Issues is a terrible way of documentation for beginners (too much to read, get too long/off-topic, unstructured, unclear which statements are outdated/accepted/reviewed and so on), so I urge everyone to write more PRs writing more beginner-friendly documentation. This does not mean that issues don't have their place. If something is wrong, please report an issue. Just that something could be updated is imho not needed to be reported.

Originally posted by @markus2330 in #4518 (comment)

Btw. an example for a useful issue is that the currently used clang-format formats something incorrectly and clang-format-15 would solve this.

Originally posted by @markus2330 in #4518 (comment)

[kodebach]

We are currently writing too much text in issues and too little text in our repo.

Sometimes this is true, but most of the time it is not.

It is utterly useless to have endless discussions in the repo on that we hopefully agree. AFAICT you want the discussion to happen in a PR, and for there to be something in the repo afterwards. That makes sense, if we know we want to do X and the discussion is about "how do we do X". But most of the time, the discussion in issues is actually about "Do we want do X at all?". It is pointless to have text in the repo that says "we might want to do X at some point, if we find time and don't change our mind".

Of course it is also my fault, not having time to create PRs of what others write in issues (as I used to do).

You also very often focus on completely he wrong part of my comments in issues. You should focus on the part relevant to the issue. My mostly rhetorical question "why do you hate issues?" to which I didn't even expect a response, is not what you should have answered; at least not in so much detail. What you should have explained is, why it would have been better if I didn't create the issue.

What you might misinterpret of me hating issues is me loving a beginner-friendly Elektra.

Adding more and more files to the doc folder does not make Elektra more beginner-friendly. In fact I would argue the opposite is the case, because it hierarchy in doc is very flat and every new file makes it harder to know where to start. Yes, the TOC-style READMEs help, but there are limits.

Issues is a terrible way of documentation for beginners (too much to read, get too long/off-topic, unstructured, unclear which statements are outdated/accepted/reviewed and so on),

Issues are not a way documenting anything, except for the 1) "hey this problem exists" 2) "we should think about X". Neither of those are aimed at beginners. Issues are inherently aimed at people already working on the project. Only as a secondary goal, issues can be useful to find out, if other people had a similar problem.

so I urge everyone to write more PRs writing more beginner-friendly documentation.

That's easy to say, when you're not the one doing the work. Why don't you write more beginner-friendly documentation? You're involved in basically everything that happens with Elektra, so you should actually have the best picture of the general stuff.

This does not mean that issues don't have their place. If something is wrong, please report an issue. Just that something could be updated is imho not needed to be reported.

So this is the issue. You see issues on GitHub purely as a bug tracker. I would argue, you are pretty alone in this opinion. Especially, since don't really use the Discussion tab either.

That simply leaves no place to put feature requests and potential ideas. Unless you want people to start a new "decision PR" for every feature request and potential idea. That would just create loads of unfinished PRs.

---

I think the main issue here is your view of issues. It is very much possible to use issue sensible and allow more than just bug reports. Just look at the Flutter and Rust projects. They both have 5k+ issues. Yes, many of those are reports of bugs and problems. But not all of them are.

[kodebach]

The main difference between our repo and Flutter/Rust is that Flutter/Rust use issue labels very extensively. This makes it much easier to find old issues and navigate open issues.

[kodebach]

Also another issue is that you (@markus2330) want to have everything explained in minute detail instead of having some faith and believing people that there is a problem (see also #4496 (comment)). You might want to argue that exactly those explanations should be committed into the repo. But I would argue for the exact opposite. First of all the explanation would have to shortened to the actually necessary parts. Otherwise it is just an information overload. But also the repo should only contain true information, so all these examples would have to be updated or removed when things change. This is just an unnecessary maintenance burden. With issues it is very clear that the information contained in old issues might be outdated.