Requirement Document generator tool

Christian Mauderer christian.mauderer at embedded-brains.de
Tue Jan 14 08:18:59 UTC 2020


On 13/01/2020 18:03, Joel Sherrill wrote:
> 
> 
> On Mon, Jan 13, 2020 at 10:04 AM Christian Mauderer
> <christian.mauderer at embedded-brains.de
> <mailto:christian.mauderer at embedded-brains.de>> wrote:
> 
>     Hello Jose,
> 
>     On 10/01/2020 17:33, Jose Valdez wrote:
>     > Hello,
>     >
>     > Regarding this topic and to start to define the python tools that
>     are more appropriate for the RTEMS community python developments, I
>     would like to propose the following tools (to be placed in RTEMS
>     Software Engineering manual):
>     >
>     > Python language version: 3.6 (minimum version for Doorstop 2.0.post2)
>     > Python coding style/standard - Google (as suggested by Gedare)
>     > Python documentation style - Google docstrings (to be in
>     accordance with coding style. Note it is supported by sphinx)
>     > Python test approach - unittest (seems to be the standard used by
>     python)
>     > Python static analysis - pylint (recommended by Google style, see
>     http://google.github.io/styleguide/pyguide.html) and mypy (catch
>     additional errors) Python code coverage - Coverage.py (seems to be
>     the standard used by python)
>     > Python third party packages - For now we are using: paramiko,
>     pyserial, pexpect, gitpython, but the list is expected to be
>     changed. I think here any third package is allowed, as long as the
>     license of the package complies with RTEMS project license.
> 
>     To be future-proof: python3 compatibility would be nearly a must-have
>     for any new library.
> 
> 
> We discussed this somewhere earlier and I thought we decided that if
> it was a core tool required for a "normal user", then it would have to
> be Python 2.x and 3.x compatible. Tools for "requirements user" or
> "pre-qualification user" (pick a name for this role), can be 3.x only 
> mainly because there was so much infrastructure required for the
> "requirements user" that already needed Python 3.x.

Yes, sorry. I used the wrong wording. What I meant was that we should
avoid libraries that support only python 2. But you have added a lot of
relevant details to this.

> 
> I think this discussion should also include "documentation producer"
> because that requires Python 3.x as well.
> 
> We just need to be conscious of the user roles that the tools are
> supporting and justify the minimum. This gives us at least 3 categories
> of tools with potentially different minimum hosting requirements. For
> example, we may not care if a certain set of tools runs on Mingw.
> 
> Obviously documented somewhere.
>  
> 
> 
>     I don't think that there are heavy license problems. The python packages
>     are most likely only used in tools. So as long as they are open enough
>     to use them on all host platforms for all development situations that
>     shouldn't be a problem. Exception: If the package is used to generate
>     code with a specific license. That generated code would have to be
>     compatible with the RTEMS license.
> 
> 
> +1 and very much non-viral and no advertising for generated code.
> 
> 
>     >
>     > Please tell me your opinions for each python tool and then we can
>     start to agree on what to use. Note that once this is defined, our
>     Qualification software will comply with the RTEMS community chosen
>     tools.
> 
>     If no one objects I would suggest to start documenting them in the RTEMS
>     Software Engineering manual. A small example project in the rtems-tools
>     repository that uses the suggested code checkers (meaning: calls them
>     during a waf build or a special 'waf check' target) would be great too.
>     That could be used for all future python based tools that are added to
>     rtems-tools (which includes the whole qualification tools).
> 
> 
> Yes. It must be enforced. Whether it is a special step or not is up for
> discussion.
> My first thought is that a special step is easy to skip.
> 
> Also can "check" be done as a pre-commit hook? 

Possible. But I'm not sure. We might can try it as soon as we have it
running in an example.

> 
> And when the style is agreed to, should existing code be auto reformatted
> to meet it?

I think this could be migrated on a per-tool basis. If we have one
project that is a sample for all future tools the checkers can be back
ported to existing tools when there is time or a good opportunity.

> 
> --joel

Best regards

Christian

> 
> 
>     Best regards
> 
>     Christian
> 
>     >
>     > Best regards
>     >
>     > José
>     >
>     > -----Original Message-----
>     > From: devel [mailto:devel-bounces at rtems.org
>     <mailto:devel-bounces at rtems.org>] On Behalf Of Chris Johns
>     > Sent: quinta-feira, 9 de janeiro de 2020 20:57
>     > To: Gedare Bloom; sebastian huber
>     > Cc: devel at rtems.org <mailto:devel at rtems.org>
>     > Subject: Re: Requirement Document generator tool
>     >
>     > On 10/1/20 4:45 am, Gedare Bloom wrote:
>     >> On Wed, Jan 8, 2020 at 11:51 PM Sebastian Huber
>     >> <sebastian.huber at embedded-brains.de
>     <mailto:sebastian.huber at embedded-brains.de>> wrote:
>     >>>
>     >>> On 08/01/2020 19:31, Gedare Bloom wrote:
>     >>>>>
>     >>>>> I agree completely on the proposed approach with Python tools.
>     >>>>>
>     >>>> Yes. Reading it I'm actually reminded about Google's approach
>     toward
>     >>>> Python which includes many of the elements mentioned. Although
>     their
>     >>>> guide is probably more comprehensive and verbose that what we
>     need, it
>     >>>> might be a useful reference for developing a set of guidelines
>     >>>> suitable for Python code in RTEMS (mainly, rtems-tools).  Here is a
>     >>>> link:
>     >>>> http://google.github.io/styleguide/pyguide.html
>     >>>>
>     >>>> I think most of the existing style has been determined and
>     driving by
>     >>>> Chris Johns. So I would also give him some credit to
>     develop/approve
>     >>>> how we plan to use Python at a project level. (**Hands Chris an
>     "RTEMS
>     >>>> Python Maintainer" hat**);)
>     >>>
>     >>> I think the Google guide would be a good start. We can always add
>     >>> project-specific exceptions/clarifications if necessary. My aim
>     is to
>     >>> use it for new code, e.g. code produced for the pre-qualification
>     >>> activity. For the code format I strongly want to use a tool for
>     this. I
>     >>> don't want to spend review time on code formatting issues.
>     >>>
>     >>> Using standard guidelines makes the RTEMS Project more
>     attractive for
>     >>> new contributors and GSoC students. I think it increases your job
>     >>> opportunities if you can refer to a successful GSoC project and
>     it shows
>     >>> that you used standard engineering practices in the project. This is
>     >>> usually not something a university education includes.
>     >>>
>     >> OK, both points make sense. I'd be happy with the Google guide, I
>     hope
>     >> Chris will comment when he can.
>     >
>     > Sorry about the erratic access. I have been knee deep in painting
>     and flooring
>     > this summer as I avoid any smoke from the fires we are having.
>     >
>     > I am fine with using a standard guide however we need to review it
>     and to make
>     > sure it fits. As an example the C++ guide from Google had some
>     good points as
>     > well as some parts I did not think offered any value but did
>     create a certain
>     > level of pain. We should also consider capturing the guide as a
>     public one
>     > belonging to someone else can and will change and that effects us.
>     I am not sure
>     > how we could do this.
>     >
>     > Chris
>     > _______________________________________________
>     > devel mailing list
>     > devel at rtems.org <mailto:devel at rtems.org>
>     > http://lists.rtems.org/mailman/listinfo/devel
>     > _______________________________________________
>     > devel mailing list
>     > devel at rtems.org <mailto:devel at rtems.org>
>     > http://lists.rtems.org/mailman/listinfo/devel
>     >
> 
>     -- 
>     --------------------------------------------
>     embedded brains GmbH
>     Herr Christian Mauderer
>     Dornierstr. 4
>     D-82178 Puchheim
>     Germany
>     email: christian.mauderer at embedded-brains.de
>     <mailto: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.
>     _______________________________________________
>     devel mailing list
>     devel at rtems.org <mailto:devel at rtems.org>
>     http://lists.rtems.org/mailman/listinfo/devel
> 

-- 
--------------------------------------------
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.


More information about the devel mailing list