See https://github.com/coreruleset/coreruleset/wiki/DevRetreat21RuleDocTemplate for previous work

• this discussion overrides some of the aspects we dealt while at Diesbach 2021

• we want to add a new "policy" (term to be defined) document that has a "set of rules".

  • will contain the description of the problem and then the list of rules that address the problem
  • the yaml schema defined in diesbach might need to be updated to centralize the information in the "common" file
  • we can start this content with the overall description of each major file now

• this process will start after LTS release

• we need the schemas for the policy and the rules updated

• cross looking at ftw schemas and future rule schemas could make this good for having one integrated document with everything related to a rule

• migration should be done:

  • automagically when possible. this means we will mostly "dump" the text written before a "SecRule" starts into the description field of the yaml, and add some other metadata like 'id' or 'title' where needed, if we can, tags, etc.
  • after the initial files are created, we will need a manual process to split the content form the "description" into the additional fields of the schema for each rule (time consuming).
  • we accept the fact that the monthly release might contain unreviewed, intermediate documentation files.
  • we include the yaml documentation files while we process them, until we can have automation for generating the '.conf' files with everything together.