search

OpenSimulationInterface / open-simulation-interface

A generic interface for the environmental perception of automated driving functions in virtual scenarios.
Other
265 stars 124 forks source link

Use of RFC 2119 terms in documentation and comments #804

Closed jdsika closed 2 months ago

jdsika commented 2 months ago

Describe the problem

While I was reviewing PRs for v3.7.0 I stumbled across this description:

// Route segments that form the route of an agent.
//
// Consecutive segments should be connected without gaps, meaning that the
// two of them should form a continuous area.
//
repeated RouteSegment route_segment = 2;

Ask your question

SHALL we use or RECOMMEND the use of terms derived from The Dublin Core, RFC 2413.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

pmai commented 2 months ago

ASAM uses more or less the ISO conventions (see https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/specification/general_docs/conventions.html for OSI), which, while I think ISO's rules on MUST vs. SHALL are misguided, is OK enough to me, and the current ASAM approach.