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