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 > > >
