wiki:GSoC/2018/Release_Notes_Generator_&_POSIX_User_Guide_Generator

Version 6 (modified by Danxue Huang, on Jun 15, 2018 at 5:27:11 PM) (diff)

--

RTEMS Release Notes Generator & RTEMS POSIX User Guide Generator

Contents

  1. RTEMS Release Notes Generator & RTEMS POSIX User Guide Generator
  2. Introduction
  3. Importance of a release notes tool
  4. Project Goal
  5. Design Development
  6. Blog
  7. Reference

Students: Danxue(Dannie) Huang

Mentors: Joel Sherrill & Chris Johns

Introduction

This project aims to enhance the performance of the release notes from Trac. Currently, the release notes could be normally used, but there need a few problems to be solved. Therefore, my ambition for this project is to make the release notes more user-friendly and strongly readable for developers. Aside from that, another project for automate conversion of Newlib Markup to Sphinx would be combined to this project. Therefore, I finally will put every work together to create a CLI tool like Python script for later developers to use.

Importance of a release notes tool

During my participation of google summer of code this year, the first project I work on is RTEMS release notes generator. Why do we need a release note tools in the RTEMS project?

  1. Missing data in release notes. Currently, the release notes could be regularly used, but some essential data are missed in the release notes. Therefore, we need to extract all of the needed data from a ticket’s page to put on the release notes.
  2. Formatting issues. Some data is not readable because of formatting issues. Therefore, it is also one of my goals to provide a better formatting of the ticket. Also, date formatting is not that reasonable. For example, the date is a local setting but not a full date.

The release notes tool fits in the RTEMS project quite well, because release notes can be generated automatically from the Trac data including all of the needed data now. Therefore, the release notes is not only more readable, but also contains more essential data.

Project Goal

This is a project to enhance the performance of the release notes from Trac. Currently, the release notes could be regularly used, but there appear few problems to be settled urgently. However, we ignore some significant features in the release notes. For example, no comments could be added to the summary of tickets, in addition to inaccurate time and formatting issues. As for another project for automate conversion of Newlib Markup to Sphinx, first, Newlib Markup should be converted to expected format supported by Sphinx. Second, RTEMS documentation could be updated with a specific version of Newlib. Finally, program would output Sphinx markup properly and automatically. For a long time, it is perfectly beneficial to RTEMS. First, adding comments to the summary of tickets would be easier for RTEMS developers to communicate with each other. Second, it would be more straightforward for customers to understand how RTEMS works. Finally, setting with absolute time and standard formatting could enhance accuracy of RTEMS.

Design Development

Design development of RTEMS release generator:

  1. At first, we need to figure out what our goal is. Our goal can be divided to a couple of tasks. For example, we need to include all needed data in the release notes, to fix formatting issues, etc.
  2. After our goal is divided into a couple of tasks, we need to figure out which one is the most essential one. At this point of time, getting needed data is the most important thing because some of needed data is missing in the release notes.
  3. Thirdly, we need to figure out what is the best solution for our problem. In general, there are two ways to get needed data. One is to parse HTML page, the other way is to parse the XML in RSS feed. Finally, we decide to use XML parser to parse the XML.

Blog

Development Blog: https://danxuehuang.blogspot.com/

Reference

  1. Preparation for understanding the project:

https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-4.11.3-release-notes.pdf

  1. Using Ticket Query:

https://devel.rtems.org/wiki/TicketQuery

  1. Tickets grouped by milestone:

https://devel.rtems.org/query?status=accepted&status=assigned&status=closed&stat us=new&status=reopened&milestone=4.11.3&col=id&col=summary&col=milestone&c ol=status&col=owner&col=type&col=priority&order=priority

  1. Example of RSS:

https://devel.rtems.org/ticket/3075

  1. Example of RSS:

https://devel.rtems.org/ticket/3075?format=rss

  1. Convert HTML to ReST:

https://pythonhosted.org/an_example_pypi_project/sphinx.html

  1. Convert HTML to ReST:

http://docutils.sourceforge.net/docs/user/rst/quickref.html

  1. Git cmd:

https://github.com/RTEMS/rtems-tools

  1. Automate Conversion of Newlib Markup to Sphinx:

https://github.com/RTEMS/rtems-tools