@otto when I get your responses to my Q's inline below I can post another revision.
On Thu, Apr 25, 2019 at 11:52 AM Otto Fowler <ottobackwa...@gmail.com> wrote: > - 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. > Format for the source files, rendered files, or both? I believe their source file format is a proprietary XML format. For rendered images, I don't have a strong opinion and am happy to leave that up to the implementer. If we want to be more opinionated, i.e. specify png, svg, jpeg, etc. I could probably be persuaded. For the source file comment, maybe it would help if I did the full write-up for 3.1 wrt instructions for how to produce the diagrams and source files from draw.io. > - Existing diagrams, in order to be modified, will have to be converted to > this format, there should be jiras for that > > Makes sense - I think I'll create those Jiras in lockstep with this vote getting approval > 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 > > I'm happy to add this as well, +1 to that. > > 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 >
