[Documentation] [TitleIndex] [WordIndex

Doc Review means that your API has been cleared (see APIReviewProcess) and that all relevant documentation for all potential users (e.g. developers vs. casual users) has been reviewed. Packages, Stacks, and Apps can all be Doc Reviewed.

We also Doc Review thirdparty components. This requires different guidelines, which are outlined below.

Process

Create a calendar event on Google Calendar, add guests

willowgarage.com_aqp3iopeia3oahnc9phu2d22b0@group.calendar.google.com,
ros-users@lists.ros.org,
individuals whom you think should attend (not everybody is on ros-review)

Include a link to the Doc review page. Give at least 48 hours between sending out the review and the requested response.

Stacks

  1. Is the description in the stack.xml informative? This shows up in the summary of the Stack wiki page.
  2. For the expected usages of your Stack, are the necessary APIs documented? (in other words, internal APIs do not need to be documented, some justification needs to be provided by the component owner as to what is/isn't internal)
  3. Do relevant usages have associated tutorials?
  4. Have all Packages in the Stack been API reviewed?

  5. Is the documentation for these APIs correct? Look for typos, things that are out-of-date, ambiguities, omissions, etc...
  6. Does the Stack conform to the StackDocumentation guidelines?

  7. Are there Packages in your Stack that don't belong

Packages

Doc Review for Packages can generally occur at the same time as the Stacks that they belong in, though there is nothing wrong with reviewing them ahead of time. They must have been API reviewed prior to this, however.

NOTE: while some of these questions are identical to questions about Stacks, the answers may in fact be different. For example, Stack tutorials address the aggregate usage of the Packages, whereas Package tutorials focus generally on just that Package.

  1. Is the description in the manifest.xml informative? This shows up in the summary at the top of the wiki page.
  2. Does the Wiki page properly introduce the user to the package. For example, if the package is a C++ library, does the wiki page guide the user to the C++ API. If the package contains a spec (e.g. URDF), is it easy to find and interact with that spec?
  3. Are there grey links in the Wiki sidebar that should be filled in, e.g. "Tutorials" and "Troubleshooting"?
  4. For the expected usages of the Package, are all of these APIs documented? (in other words, internal APIs do not need to be documented, some justification needs to be provided by the package owner as to what is/isn't internal)
  5. Do relevant usages have associated tutorials? (you can ignore this if a Stack-level tutorial covers the relevant usage)
  6. If there are hardware dependencies of your Package, are these documented?
  7. Is it clear to an outside user what the roadmap is for your Package? It's okay if this roadmap is on the Stack roadmap.
  8. Is it clear to an outside user what the stability is for your Package?
  9. Are concepts introduced by your Package well illustrated?
  10. Is the research related to your Package referenced properly? i.e. can users easily get to relevant papers?
  11. Are any mathematical formulas in your Package not covered by papers properly documented?

For each launch file in a Package

  1. Is it clear how to run that launch file?
  2. Does the launch file start up with no errors when run correctly?
  3. Do the Nodes in that launch file correctly use ROS_ERROR/ROS_WARN/ROS_INFO logging levels?

Once the package is Doc Reviewed, set the review status in the manifest to "doc reviewed".

Thirdparty Doc Review

Reviewing thirdparty Packages follows a slightly different process to acknowledge the fact that we don't have control over the API of these Packages. We still Doc Review these Packages as there are some important things to check before we release a thirdparty Package with a Stack.

In general, the answers to these questions should be available in the manifest of the Package

  1. Is the version that we're using correct?
  2. Is it clear to an outside user which version we're using, and why?
  3. What is the update policy for versions going forward?
  4. Is this package available from the OS package managers instead? There is a strong preference to using these instead of maintaining our own
  5. Have all patches been submitted back? What version do you expect these patches to be included in?

Once the package is Doc Reviewed, set the review status in the manifest to "3rdparty doc reviewed".

Completing a Review

If you have completed Doc Review, please mark the relevant manifest.xml or stack.xml with Doc reviewed in the <review> status. Also note the date of the review in the notes attribute.


2018-06-18 22:56