- We need to specify the format I think, and then say that draw io is the tool for the format and not just specify the tool. - Existing diagrams, in order to be modified, will have to be converted to this format, there should be jiras for that
2.1 "New features and significant bug fixes should be documented in the JIRA. Appropriate architecture diagrams should be created in https://www.draw.io/ and committed “ "New features and significant bug fixes should be documented in the JIRA. Appropriate architecture diagrams should be created in https://www.draw.io/ and committed. Diagrams may be requested of PR submitters during review either as documentation or as an aid to the reviewer “ We could/should/can use the diagrams as - documentation - simple aids for understanding PRs and communication ( Nick and I used them for such yesterday to great effect to make sure we were on the same page ). I’m not sure we don’t want to have that blurb in there On April 25, 2019 at 12:57:47, Michael Miklavcic ( michael.miklav...@gmail.com) wrote: I'd like to propose a vote to change our dev guidelines which will clarify the tooling we use to produce diagrams and share the source files for those diagrams. The original discuss thread is noted at the end of this email. I propose the dev guidelines https://cwiki.apache.org/confluence/display/METRON/Development+Guidelines and PR checklist https://github.com/apache/metron/blob/master/.github/PULL_REQUEST_TEMPLATE.md#for-documentation-related-changes be changed in the following ways: 1. We specify that draw.io is the free tool of choice for sharing diagrams in Metron and that the source files will be maintained/shared in source control. 2. Under "1.1 Contributing A Code Change" 1. Change "New features and significant bug fixes should be documented in the JIRA and appropriate architecture diagrams should be attached. Major features may require a vote." to "New features and significant bug fixes should be documented in the JIRA. Appropriate architecture diagrams should be created in https://www.draw.io/ and committed to source control with their XML source files and final rendered image. Major features may require a vote." 3. Under "2.4 Documentation" 1. Add a new section with instructions entitled "Creating and Modifying Diagrams". This section would provide basic instructions for downloading source files from draw.io. 4. Add a new checkbox item under PR checklist heading "For documentation related changes" with the following text 1. Have you ensured that any documentation diagrams have been updated, along with their source files, using draw.io? See https://cwiki.apache.org/confluence/display/METRON/Development+Guidelines for instructions. We require a minimum of 72 hours for a vote, not typically including weekend days. I'd like to leave this vote open until Tuesday, 12PM EDT. Please vote +1, -1, or 0 to abstain, and also indicate if your vote is binding or non-binding. https://lists.apache.org/thread.html/3ae02f1e32044b1a7648899700d44611aefdab6caa09fb3196292425@%3Cdev.metron.apache.org%3E Cheers, Mike
