Hi :) On 20.06.2022 09:42, c.buhtz@posteo.jp wrote:
I think README.md is a good start; quick and easy. Then we see how it develops and what the content of that section really is.
Maybe I misunderstand term "Known Problems and Workarounds". When there is a "problem" with BIT or a situation where you need a "workaround" for than it is a bug. In that case there should be an open Issue with all relevant information's to reproduce and workaround that problem/bug/issue. Because of that understanding I wouldn't say that we need an extra README.md or wiki section for that because we still have the Issues open; it would be redundant documentation.
But I suppose you mean something like edgy use cases or rare situations. An example what comes into my mind is the migration of a backup setup. BIT runs on your PC and stores the files via Samba or SSH on another NAS in your local network. Then you completely reinstall your PC or you buy a new one. How to install BIT and set it up that way that it goes on with the still existing backups on the NAS? It is possible and I have done this multiple times. But it is not (good) documented. Did you mean something like this?
I agree that open Issues should be the definitive place to track open bugs. But there are a small number of "hot" issues (Python 3.10 compat, rsync 3.2.4 compat, the duplicate storage of hardlinked-with-differing-permissions files issue) which many people run into. The Github issues do contain the necessary workaround information, but they are tiresome to navigate. I think it's good to have a well-visible text section (like in README.md) that basically acknowledges: "Yes, we're aware of that specific, widespread problem, we're just getting started on fixing the code, here's the known workaround for now, thank you for your patience."
Just my thoughts. Anyway. Just do it so and we will see what the content of this sections is. ;)
Yes please, and thanks for the initiative, Alex :)
Another idea that comes to my mind. For an answer to the "is that project dead" question in Issues, we should have a section (in wiki, faq or your "known problems") where we can link to and then close the Issue. Would save time. ;)
I think this would be perfect to go in the same place in README.md! Like so: "Known Problem #0: This project isn't maintained – Answer: It's been dormant for a while, but a small team has started to get things moving again. Stick with us, we all love backintime :)" (And maybe a hint to this mailing list.) And then we close the Issue ;)
By the way there still is a FAQ section in the wiki https://github.com/bit-team/backintime/wiki/FAQ It seems to me that most of its content covers use cases and user-problems (not bugs).
Yes, that looks like standard documentation, not the kind of "emergency meta-information" that is suggested here. Cheers! :) Michael