Requirement Document generator tool

Mon Jan 13 17:03:32 UTC 2020

On Mon, Jan 13, 2020 at 9:06 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.
>
> 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.
>
Yes, I would like something similar to Christian's wording instead of
specifing a list of 3rd party packages.

I think we can start with the proposed set of tools/requirements. If
problems in the coding style arise, we can evolve. The Google Python
Style Guide is given as a single markdown file in
https://github.com/google/styleguide/pyguide.md. It is licensed CC-By
3.0. We should mirror it on our infrastructure and track the
version/changes.

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