Requirement Document generator tool

Wed Jan 8 18:31:59 UTC 2020

On Wed, Jan 8, 2020 at 9:47 AM Joel Sherrill <joel at rtems.org> wrote:
>
>
>
> On Fri, Jan 3, 2020 at 7:26 AM Sebastian Huber <sebastian.huber at embedded-brains.de> wrote:
>>
>> Hello Jose,
>>
>> On 03/01/2020 11:52, Jose Valdez wrote:
>> >>>> Should be in rtems-tools? If so, in which place?
>> >>> I think this is the best place given the information I have. I would
>> >>> need to have more detail before I could provide any specific direction here.
>> >>
>> >> All host tools are in rtems-tools so at this point, there isn't another place.
>> >>
>> >> But I agree with Chris. We need more information.
>> >>
>> > We need to know:
>> > * Language(s) used for the tool
>> > * Host requirements to run the tool
>> > * Licensing of the tool
>> >
>> > Putting the pre-qual tools into rtems-tools seems reasonable, but a discussion should happen within the RTEMS Project community/maintainers to do that.
>> >
>> > JV02012019, Joel and Gedare:
>> >
>> > We need to know:
>> > * Language(s) used for the tool - python (>= 3.7)
>> > * Host requirements to run the tool - Debian 10
>> > * Licensing of the tool - BSD-2-Clause
>> >
>> > Please read the section 4 of the document SDD-301.pdf, I am sending in attach (removed to go to rtems devel mailing list!!). This provides an overview of the tool (I think we missed to give you this overview).
>> > For more information you may also take a look in the SRS-300.pdf and TI-003 (just the conclusions on each section).
>> > Note that the information presented in these documents is subjected to be changed, but as I said, the idea is for you to have a better understanding about the big picture of the project. The details will be discussed (and iterated) alongside the project execution.
>>
>> the aim is to write all tools in the ESA pre-qualification activity in
>> Python. Derivatives of existing stuff will use the respective license.
>> New stuff will use the BSD-2-Clause license for code and CC-BY-SA-4.0
>> for documentation.
>>
>>  From an RTEMS Project point of view, project-specific documentation is
>> irrelevant in general. It can be used as a complementary material to
>> explain things intended for integration, however, all content relevant
>> to things integrated in the RTEMS Project must move to the right places
>> in the RTEMS Project.
>>
>> We have to settle on a specific Python version. Since Doorstop 2.0.post2
>> is already selected as the tool for requirements management and it
>> requires at least Python 3.6 I think it makes sense to use this version
>> as well for new tools. In contrast to the build system I think a Python
>> 2 compatibility is unnecessary.
>>
>> Tools which belong also to the work flow of an RTEMS user, e.g. the
>> RTEMS Tester, should still work with Python 2.
>>
>> The decisions, justification, and requirements with respect to the tool
>> language selection should be recorded in the RTEMS Software Engineering
>> manual.
>>
>> Once a tool language is selected. We need a coding style and standard.
>> We should choose an existing one, e.g.
>>
>> https://www.python.org/dev/peps/pep-0008/
>>
>> There should be tools to check the coding style automatically. I don't
>> want the situation we have with the RTEMS sources. For Python there are
>> plenty of tools, guides, and documentation available. We just have to
>> pick some for the RTEMS Project and document this in the RTEMS Software
>> Engineering manual.
>>
>> The compatible Python versions (e.g. 3.6+), coding style (e.g. black -l
>> 80), documentation style (e.g. pydocstyle), test approach (standard
>> Python unittest and unittest.mock), static analysis (e.g. mypy and
>> pylint), code coverage, use of third-party packages, etc. need to be
>> discussed with the RTEMS Project and the conclusions should be added to
>> the RTEMS Software Engineering manual.
>>
>> Running the checkers, test suites, code coverage, etc. should be done
>> though the build system (in rtems-tools this is waf). The Doorstop
>> project is a good example how this can be set up.
>>
>> If you look at the current RTEMS Software Engineering manual you will
>> find next to nothing with respect to Python code. You can set now the
>> standards (after discussion on devel at rtems.org). You should do this
>> before you send the first line of Python code for review.
>
>
> 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**) ;)

>>
>>
>> Once the frame for Python development is settled. We need a high level
>> description of the purpose of the tools, the inputs and the outputs.
>> This high level description should be integrated in the RTEMS Project
>> documentation. If you want to get things integrated in the RTEMS Project
>> then you have make sure that it is good and general enough so that
>> others can continue to work on it. In the worst case everything should
>> be maintainable by the RTEMS Project without you in the future.
>
>
> Describing the purpose, inputs and outputs, and high level description should
> go a long way to having a theory of operation for the tools. It is important to
> know what software engineering purpose the tool satisfies and its role in
> the pre-qualification workflow.
>
> Thanks for taking the time Sebastian for the nice write up.
>
> --joel
>
>>
>>
>> --
>> Sebastian Huber, embedded brains GmbH
>>
>> Address : Dornierstr. 4, D-82178 Puchheim, Germany
>> Phone   : +49 89 189 47 41-16
>> Fax     : +49 89 189 47 41-09
>> E-Mail  : sebastian.huber at embedded-brains.de
>> PGP     : Public key available on request.
>>
>> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.