[Reportbug-maint] Bug#890680: Bug#890680: reportbug: python3-reportbug submodules are not well documented

[Sandro Tosi]

On Sun, Feb 18, 2018 at 5:03 AM, Nis Martensen <nis.martensen at web.de> wrote:
> Hey Sandro!
>
> On 18-02-2018 05:49, Sandro Tosi wrote:
>> Hey Nis!
>>
>>> The reportbug source code has some issues that make it hard to review:
>>
>>
>> thanks for working on this! even if i dont want to mess with your
>> plans, let me tell you that if you really want to work on this "qa"
>> kind-of activity for reportbug, i think the area that will give the
>> biggest impact is improvements to the test suite: currently part of
>> the code is not covered well (or at all) and i did a poor job at
>> adding tests for bugs that were filed and fixed; also i've always
>> wished to be able to test the interactive part in reportbug (maybe
>> mocking the input method).
>
> Extending the test suite is actually the goal here. It's just hard to
> add tests for functions of which you don't know what they're supposed to
> do exactly. So reading the code and taking notes is the first step.

oh great to hear we're one the same page on that! :)

>
>>>  - Most functions in reportbug/*.py do not have a docstring, or only a very
>>>    brief one. Some functions still have many parameters, and some return quite
>>>    complex objects.
>>>  - module-internal functions are not prefixed with an underscore, so it is hard
>>>    to tell which functions are meant for external use.
>>
>> can we do something now, though? as of now they are all public
>> functions, removing them by making them private can break someone's
>> code (ok ok it's rather remote possibility but still)
>
> You are of course correct. `apt-cache rdepends python3-reportbug` only
> lists reportbug, though.  I also spent some time searching with
> codesearch.debian.net some weeks ago, and couldn't find anything else.
> I believe it is quite unlikely that there are any users outside debian.

i was more thinking of tools external to debian, like scripts from
operators using those functions

> The current patch set includes making functions private. Let me know if
> you don't want this part.

are the changes to make the private in separate commits or among the
docstrings changes? the former would help in review the change

>>> I'm slowly working on patches.
>>
>> i would suggest to submit of your early patches soon, so that i can
>> have a look and eventually comment earlier
>
> It is quite a lot already. Will send later today.

sorry about that :(

> Are you planning to move reportbug to salsa in the future?  It might
> make this kind of review easier.

i just did and migrated reportbug to
https://salsa.debian.org/reportbug-team/reportbug - wanna try the
merge request thing ah! :)



-- 
Sandro "morph" Tosi
My website: http://sandrotosi.me/
Me at Debian: http://wiki.debian.org/SandroTosi
G+: https://plus.google.com/u/0/+SandroTosi