Based on some requested changes from Otto, I'm pulling the vote on this. I haven't had a chance to make the revisions yet, and will restart the vote when I have a chance to get those finished.
On Fri, Apr 26, 2019 at 1:27 PM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > That works too > > On Fri, Apr 26, 2019, 12:20 PM Otto Fowler <ottobackwa...@gmail.com> > wrote: > >> When I say module, I mean at the root of any module, so each module could >> have it’s own diagrams. >> And the project root wold have diagrams for the ‘overall' >> >> >> On April 26, 2019 at 13:44:30, Michael Miklavcic ( >> michael.miklav...@gmail.com) wrote: >> >> The convention that seems to have been followed thus far has been to plop >> the images in the root of the module they're relevant to. Maybe relocating >> them to a central place would make it easier. The site-book image link >> rewriting might be simpler then as well. The only downside to this >> approach >> would be that the artifacts are split from their respective modules, but I >> honestly don't see that as a problem. >> >> On Fri, Apr 26, 2019, 11:40 AM Otto Fowler <ottobackwa...@gmail.com> >> wrote: >> >> > On April 26, 2019 at 13:19:05, Michael Miklavcic ( >> > michael.miklav...@gmail.com) wrote: >> > >> > @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. >> > >> > >> > I think what you say would be ok then, if draw io only has one source >> > format. >> > >> > I don’t care about the image format either, I’m surprised nobody has a >> > strong opinion about it. >> > >> > Do we want a standard place to put the diagrams? >> > >> > module/ >> > - diagrams/ >> > - foo.xml >> > - foo.png >> > - pr1234.xml >> > - pr1234.jpeg >> > - METRON-13244.xml >> > - METRON-13244.png >> > - EnrichementArchitecture.xml >> > - EnrichementArchitecture.png >> > >> > >> > >> > >> > >> > >> > > - 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 >> > > >> > >> >
