Requirement Document generator tool

Mon Jan 13 17:03:09 UTC 2020

On Mon, Jan 13, 2020 at 10:04 AM Christian Mauderer <
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.

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?

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

--joel

>
> Best regards
>
> Christian
>
> >
> > Best regards
> >
> > José
> >
> > -----Original Message-----
> > From: devel [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
> > 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> 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
> > http://lists.rtems.org/mailman/listinfo/devel
> > _______________________________________________
> > devel mailing list
> > 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.
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200113/536e6fbd/attachment-0001.html>