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