Documentation, especially about known problems?
Hi, I am glad about the current initiative to keep BiT alive. The easiest (but still helpful) thing to start with, would be to update the documentation. The issues on github contain a lot of information, some of which should also be consolidated at one place, I think. [1] refers to a FAQ page and an external (readthedocs.io) page. I suggest to also create a page with a title like "Known problems" that can directly be found from [1]. It could e.g. include information about - the fact that BiT does not start on Ubuntu 22.04, together with possible workarounds (strictly speaking, no longer a problem of BiT itself, but of Ubuntu, but still relevant to a lot of users) - the changed permission behaviour in newer Bit versions - incompatibility with rsync 3.2.4 What do you think? [1] https://github.com/bit-team/backintime/wiki Regards, Alex
Dear Alex, welcome the list and thank you for your thoughts. On 2022-06-17 14:49 "Alex S." <alex4983@gmx.de> wrote:
The easiest (but still helpful) thing to start with, would be to update the documentation. The issues on github contain a lot of information, some of which should also be consolidated at one place, I think. [1] refers to a FAQ page and an external (readthedocs.io) page. I suggest to also create a page with a title like "Known problems" that can directly be found from [1].
I am not sure if I understand all this and maybe some things are mixed up here. I assume with the term "documentation" you don't mean a user-guide or code-reference-guide. Correct? You mean something like a protocol or document with the known problems. Am I right? Kind Christian
Hi everyone, I think Alex is proposing a solution to this current situation: 1) Someone encounters a problem with backintime, 2) they google around and find an open Github issue, 3) they read through the issue until they find a workaround that helps. As far as I undestand, Alex would like to create a "Known Problems and Workarounds" section somewhere (maybe in Github's README.md), so that people can find the "known workarounds to known problems" more easily. Is that right? Cheers, Michael On 18.06.2022 10:43, c.buhtz@posteo.jp wrote:
Dear Alex,
welcome the list and thank you for your thoughts.
On 2022-06-17 14:49 "Alex S." <alex4983@gmx.de> wrote:
The easiest (but still helpful) thing to start with, would be to update the documentation. The issues on github contain a lot of information, some of which should also be consolidated at one place, I think. [1] refers to a FAQ page and an external (readthedocs.io) page. I suggest to also create a page with a title like "Known problems" that can directly be found from [1].
I am not sure if I understand all this and maybe some things are mixed up here.
I assume with the term "documentation" you don't mean a user-guide or code-reference-guide. Correct? You mean something like a protocol or document with the known problems. Am I right?
Kind Christian
Hi, yes, this is what I meant, especially your point 3). I think your idea of a section "Known Problems and Workarounds" on Github's README.md would really be helpful (better than the wiki page I suggested). Maybe I will create a pull request, if no one else does this and there is no resistance ;) Of course, it would even be better, if we got those problems fixed some day :) Regards, Alex On 2022-06-19 14:15, Michael Büker wrote:
Hi everyone,
I think Alex is proposing a solution to this current situation:
1) Someone encounters a problem with backintime, 2) they google around and find an open Github issue, 3) they read through the issue until they find a workaround that helps.
As far as I undestand, Alex would like to create a "Known Problems and Workarounds" section somewhere (maybe in Github's README.md), so that people can find the "known workarounds to known problems" more easily. Is that right?
Cheers, Michael
On 18.06.2022 10:43, c.buhtz@posteo.jp wrote:
Dear Alex,
welcome the list and thank you for your thoughts.
On 2022-06-17 14:49 "Alex S." <alex4983@gmx.de> wrote:
The easiest (but still helpful) thing to start with, would be to update the documentation. The issues on github contain a lot of information, some of which should also be consolidated at one place, I think. [1] refers to a FAQ page and an external (readthedocs.io) page. I suggest to also create a page with a title like "Known problems" that can directly be found from [1].
I am not sure if I understand all this and maybe some things are mixed up here.
I assume with the term "documentation" you don't mean a user-guide or code-reference-guide. Correct? You mean something like a protocol or document with the known problems. Am I right?
Kind Christian
Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: alex4983@gmx.de
I'm in favor of including such a section :) Could you compile the information, Alex? Best, Michael On 19.06.2022 22:43, Alex S. wrote:
Hi,
yes, this is what I meant, especially your point 3). I think your idea of a section "Known Problems and Workarounds" on Github's README.md would really be helpful (better than the wiki page I suggested). Maybe I will create a pull request, if no one else does this and there is no resistance ;) Of course, it would even be better, if we got those problems fixed some day :)
Regards, Alex
On 2022-06-19 14:15, Michael Büker wrote:
Hi everyone,
I think Alex is proposing a solution to this current situation:
1) Someone encounters a problem with backintime, 2) they google around and find an open Github issue, 3) they read through the issue until they find a workaround that helps.
As far as I undestand, Alex would like to create a "Known Problems and Workarounds" section somewhere (maybe in Github's README.md), so that people can find the "known workarounds to known problems" more easily. Is that right?
Cheers, Michael
On 18.06.2022 10:43, c.buhtz@posteo.jp wrote:
Dear Alex,
welcome the list and thank you for your thoughts.
On 2022-06-17 14:49 "Alex S." <alex4983@gmx.de> wrote:
The easiest (but still helpful) thing to start with, would be to update the documentation. The issues on github contain a lot of information, some of which should also be consolidated at one place, I think. [1] refers to a FAQ page and an external (readthedocs.io) page. I suggest to also create a page with a title like "Known problems" that can directly be found from [1].
I am not sure if I understand all this and maybe some things are mixed up here.
I assume with the term "documentation" you don't mean a user-guide or code-reference-guide. Correct? You mean something like a protocol or document with the known problems. Am I right?
Kind Christian
Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: alex4983@gmx.de
Bit-dev mailing list -- bit-dev@python.org To unsubscribe send an email to bit-dev-leave@python.org https://mail.python.org/mailman3/lists/bit-dev.python.org/ Member address: foss@michael-bueker.de
Good morning Alex, Am 19.06.2022 22:43 schrieb Alex S.:
Maybe I will create a pull request, if no one else does this and there is no resistance ;)
No resistance from me. I am happy with every piece of documentation. Am 19.06.2022 22:43 schrieb Alex S.:
I think your idea of a section "Known Problems and Workarounds" on Github's README.md would really be helpful (better than the wiki page I suggested).
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? Just my thoughts. Anyway. Just do it so and we will see what the content of this sections is. ;) 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. ;) 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). Kind Christian
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
Am 20.06.2022 10:43 schrieb Michael Büker:
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."
OK, now I got it. ;) Thanks.
Hi, I created the PR :) https://github.com/bit-team/backintime/pull/1261 Regards, Alex
participants (3)
-
Alex S. -
c.buhtz＠posteo.jp -
Michael Büker