Requirement Document generator tool

Thu Jan 30 09:35:09 UTC 2020

On 29/01/2020 23:48, Chris Johns wrote:
> On 29/1/20 7:40 pm, Christian Mauderer wrote:
>> On 28/01/2020 23:15, Chris Johns wrote:
>>> On 28/1/20 10:22 pm, Christian Mauderer wrote:
>>>> I'm quite indifferent which style we use
>>>
>>> But you are arguing a position, such as ...
>>>
>>>> but do you really think that it
>>>> is a good idea to roll our own RTEMS-Python-style instead of using one
>>>> of the big ones (like PEP8, Google or some other that might is a better
>>>> fit for existing code). Rolling our own would lead to:
>>>>
>>>> 1. Long discussions about what is THE RIGHT STYLE (already started in
>>>> this mail).
>>>>
>>>> 2. A lot of problems that there is no tool that formats or checks
>>>> whether code is in THE RIGHT STYLE.
>>>>
>>>> 3. More discussions later because some other developer thinks that THE
>>>> RIGHT STYLE is wrong.
>>
>> You are right that I argue against home-grown styles. I learned that
>> style discussions are quite similar to religious discussions. Everyone
>> beliefs that his style is the only right one. Using a big one makes it
>> simpler to avoid discussions because a lot of people know it.
> 
> And yet you inherit issues a large organisation cannot correct because
> historically a style is difficult to change and they are wedged. They need to be
> reviewed and evaluated.

That's why I originally thought of defining a style for _new_ code with
an optional _slow_ migration if some existing code is touched. Of course
the style should be compatible with the views how the old code should
look in the future too. The patches were just for an estimate how much
influence the suggested styles could have. I would never expect that any
big patch with automated changes would be acceptable without a thorough
review. I wouldn't accept that myself.

> 
>> Please don't get me wrong: I'm OK with another style too. The relevant
>> result is that we have _one_ style in RTEMS that can be automatically
>> checked. 
> 
> I find it interesting this view is OK for Python and the tools and yet we do not
> have automatic checking for the score's C. Or do we?

It would be great if we would have automatic checking for C too. There
are big projects that have something like that and it's really
convenient. For example for Linux before you send a patch you can just
run "./scripts/checkpatch.pl some.patch" and it will give you everything
you should fix before sending it to the list. That removes at least one
round of review.

But I think implementing that would be a lot bigger task than the one we
are just discussing. One of the first problems would be finding a style
checker that can produce _exactly_ the coding style that is defined for
score. And also I'm happy to discuss approaches for something like that
it would start to be of-topic for this thread. So if you want to discuss
details about automatic style checking for score we should create an
extra topic. Maybe we could even create a GSoC project for something
like that?

> 
>> That also will make patch review simpler because we as
>> maintainers don't have to do the style review by hand.
> 
> This is often more about those coding than those reviewing.

Sorry, I think I don't fully understand you here.

> 
>>> I wrote the code, I know it and I need to maintain it. All I am asking is if
>>> pre-qual wants rules then I suggest they find some common ground.
>>
>> I agree that it is a good idea to find something that is acceptable for all.
>>
>>>
>>> I wonder how libbsd.py goes with these rules. Also all the wscript files which
>>> are also python and also the RSB would be covered.
>>
>> Most likely not well. But that's the problem: We already have a bunch of
>> different styles. Let's try to agree on one before we get lots of extra
>> code. A lot of pre-qualification code will be python. Therefore now is
>> the best time.
> 
> You may know more than me about this. We have been given no information about
> the project's plans or these tools and is becoming frustrating. Joel and I have
> asked on a number occasions. The silence is testing our patience.

I'm really sorry for that. Like I mentioned earlier I'm not really very
good with the overview over this project too. I'll try to discuss this
with Sebastian and Thomas as soon as Sebastian is back from vacation.

> 
> How about we put a python rules discussion on hold until the intentions of the
> pre-qual project are presented publicly and in a manner we can all digest. I
> have spent enough time and energy discussing this stuff and it is not clear to
> me we are in a position to accept what is to be written.

If you want to stop the discussion, I have to accept that. Please just
answer with "this needs further discussion but not now" for all parts
where you think we should stop right now.

But please note that our current discussion is in my opinion more of a
basic discussion that is only triggered by the pre-qualification
efforts. It's not really relevant whether new tools are added by
pre-qualification in the next year or for some other reasons in the next
five or ten years. Our Python code base is growing and it will become
harder to migrate to some common style with each added snipped of Python
code.

To come back to your argument regarding C code: For score there is at
least a defined coding style that could be used as a basis for automatic
checks. We currently don't have a defined or recommended style for
Python. So we will have a lot less uniform Python code base than we have
in score in a few years.

> 
>> If I understood you correctly your main problem with both suggested ones
>> (PEP8 and Google) is that multi line lists have been put together into
>> one liners and dictionaries with aligned fields are not aligned anymore?
> 
> They cannot be touched ...
> 
> https://git.rtems.org/rtems-source-builder/tree/source-builder/sb/darwin.py#n41
> https://git.rtems.org/rtems-source-builder/tree/source-builder/sb/freebsd.py#n50
> https://git.rtems.org/rtems-source-builder/tree/source-builder/sb/linux.py#n54
> https://git.rtems.org/rtems-source-builder/tree/source-builder/sb/linux.py#n104
> https://git.rtems.org/rtems-source-builder/tree/source-builder/sb/linux.py#n104
> https://git.rtems.org/rtems-source-builder/tree/source-builder/sb/options.py#n56
> https://git.rtems.org/rtems-libbsd/tree/libbsd.py#n59
> https://git.rtems.org/rtems-libbsd/tree/libbsd.py#n108
> https://git.rtems.org/rtems-libbsd/tree/libbsd.py#n148
> 
> I could go on but I think this list should highlight the issue.
> 

I agree that the readability would suffer for cases like that. So we
will have to find a solution for that.

>> About correct?
> 
> The lack of space around the arguments is also a change that is silly and I do
> not want changed.

I think that is based on the "official" python style (which is PEP-0008):

https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements

> 
> The biggest challenge who ever finally proposes these rules faces is the RSB. It
> is very difficult to know if you have broken it. It has taken years to converge
> to the level of stability we have. All changes in here would need a close review
> and that something I am not excited about.

I agree that all changes should be reviewed closely. Again: I'm in favor
of finding something acceptable that can be used for new tools and then
try to start a slow migration maybe even over years. Note that this is a
purely personal preference and I don't have an idea whether it matches
the targets of pre-qualification or not.

Best regards

Christian

> 
> Chris
> 

-- 
--------------------------------------------
embedded brains GmbH
Herr Christian Mauderer
Dornierstr. 4
D-82178 Puchheim
Germany
email: christian.mauderer at embedded-brains.de
Phone: +49-89-18 94 741 - 18
Fax:   +49-89-18 94 741 - 08
PGP: Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.