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