Re: [RESULT] [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
Dev guidelines have been updated - https://cwiki.apache.org/confluence/display/METRON/Development+Guidelines PR is up for the PR checklist change - https://issues.apache.org/jira/browse/METRON-2107 - https://github.com/apache/metron/pull/1401 On Wed, May 8, 2019 at 10:17 AM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > Vote has passed. Voting was: > 2 binding +1's (Mike Miklavcic, Otto Fowler) > 1 non-binding +1 (Jon Zeolla) > > I will start making the changes to the dev guidelines today. > > Vote thread - > https://lists.apache.org/thread.html/dccecd41314e76eed7440ab8214ab5ee1ed28724e6f0e545c68ea5e0@%3Cdev.metron.apache.org%3E > >
[RESULT] [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
Vote has passed. Voting was: 2 binding +1's (Mike Miklavcic, Otto Fowler) 1 non-binding +1 (Jon Zeolla) I will start making the changes to the dev guidelines today. Vote thread - https://lists.apache.org/thread.html/dccecd41314e76eed7440ab8214ab5ee1ed28724e6f0e545c68ea5e0@%3Cdev.metron.apache.org%3E
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
Good idea - I will make that addendum. I would consider that, ipso facto, acceptable to everyone on the thread unless they say otherwise - considering the entire point of this vote is to standardize the diagram tool, it would be inconsistent with that goal to use the word "should." "Must" makes sense here. On Fri, May 3, 2019, 3:19 PM zeo...@gmail.com wrote: > +1 non-binding > > I would only prefer that we change "Appropriate architecture diagrams > should be created in" to "Appropriate architecture diagrams must be created > in" but I'm good either way. > > - Jon Zeolla > zeo...@gmail.com > > > On Fri, May 3, 2019 at 10:18 AM Michael Miklavcic < > michael.miklav...@gmail.com> wrote: > > > Yes, it is free James. We made sure of that in the original discussion. > > > > On Thu, May 2, 2019 at 9:33 PM James Sirota wrote: > > > > > i am ok with it as long as we are not forcing people to buy stuff > > > > > > 02.05.2019, 18:18, "Michael Miklavcic" : > > > > Here's the latest discussion on the subject: > > > > > > > > > > https://lists.apache.org/thread.html/0aa2b0b9ed4a0f0b0d8bb018c618e62de196565f9af71f347e504076@%3Cdev.metron.apache.org%3E > > > > > > > > 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. 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. 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 as per section 2.4. Diagrams may be requested > > of > > > PR > > > > submitters during review either as documentation or as an aid > to > > > the > > > > reviewer. Major features may also require a vote.">> > > > >2. Under "2.4 Documentation" > > > > 1. New line item <<"Diagrams - We save architecture diagram > > source > > > > files in an xml format rendered by draw.io (instructions > below). > > > This > > > > is the free tool of choice that we've agreed to use for > > exchanging > > > > diagrams and their source files in Metron.">> > > > > 2. New line item < > > > "/images-source" and rendered diagrams and images > > > belong in > > > > "/images." > > > > 3. New subsection <<"Creating and Modifying Diagrams">>. This > > > section > > > > would provide basic instructions for downloading source files > > from > > > > draw.io. > > > >3. 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. > > > >4. Here is the Jira for migrating/redoing existing diagrams > > > > 1. https://issues.apache.org/jira/browse/METRON-2099 > > > > > > > > We require a minimum of 72 hours for a vote, not typically including > > > > weekend days. I'd like to leave this vote open until Wednesday 5/8, > > 12PM > > > > EDT. Please vote +1, -1, or 0 to abstain, and also indicate if your > > vote > > > is > > > > binding or non-binding. > > > > > > --- > > > Thank you, > > > > > > James Sirota > > > PMC- Apache Metron > > > jsirota AT apache DOT org > > > > > > > > >
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
+1 non-binding I would only prefer that we change "Appropriate architecture diagrams should be created in" to "Appropriate architecture diagrams must be created in" but I'm good either way. - Jon Zeolla zeo...@gmail.com On Fri, May 3, 2019 at 10:18 AM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > Yes, it is free James. We made sure of that in the original discussion. > > On Thu, May 2, 2019 at 9:33 PM James Sirota wrote: > > > i am ok with it as long as we are not forcing people to buy stuff > > > > 02.05.2019, 18:18, "Michael Miklavcic" : > > > Here's the latest discussion on the subject: > > > > > > https://lists.apache.org/thread.html/0aa2b0b9ed4a0f0b0d8bb018c618e62de196565f9af71f347e504076@%3Cdev.metron.apache.org%3E > > > > > > 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. 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. 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 as per section 2.4. Diagrams may be requested > of > > PR > > > submitters during review either as documentation or as an aid to > > the > > > reviewer. Major features may also require a vote.">> > > >2. Under "2.4 Documentation" > > > 1. New line item <<"Diagrams - We save architecture diagram > source > > > files in an xml format rendered by draw.io (instructions below). > > This > > > is the free tool of choice that we've agreed to use for > exchanging > > > diagrams and their source files in Metron.">> > > > 2. New line item < > > "/images-source" and rendered diagrams and images > > belong in > > > "/images." > > > 3. New subsection <<"Creating and Modifying Diagrams">>. This > > section > > > would provide basic instructions for downloading source files > from > > > draw.io. > > >3. 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. > > >4. Here is the Jira for migrating/redoing existing diagrams > > > 1. https://issues.apache.org/jira/browse/METRON-2099 > > > > > > We require a minimum of 72 hours for a vote, not typically including > > > weekend days. I'd like to leave this vote open until Wednesday 5/8, > 12PM > > > EDT. Please vote +1, -1, or 0 to abstain, and also indicate if your > vote > > is > > > binding or non-binding. > > > > --- > > Thank you, > > > > James Sirota > > PMC- Apache Metron > > jsirota AT apache DOT org > > > > >
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
Yes, it is free James. We made sure of that in the original discussion. On Thu, May 2, 2019 at 9:33 PM James Sirota wrote: > i am ok with it as long as we are not forcing people to buy stuff > > 02.05.2019, 18:18, "Michael Miklavcic" : > > Here's the latest discussion on the subject: > > > https://lists.apache.org/thread.html/0aa2b0b9ed4a0f0b0d8bb018c618e62de196565f9af71f347e504076@%3Cdev.metron.apache.org%3E > > > > 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. 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. 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 as per section 2.4. Diagrams may be requested of > PR > > submitters during review either as documentation or as an aid to > the > > reviewer. Major features may also require a vote.">> > >2. Under "2.4 Documentation" > > 1. New line item <<"Diagrams - We save architecture diagram source > > files in an xml format rendered by draw.io (instructions below). > This > > is the free tool of choice that we've agreed to use for exchanging > > diagrams and their source files in Metron.">> > > 2. New line item < > "/images-source" and rendered diagrams and images > belong in > > "/images." > > 3. New subsection <<"Creating and Modifying Diagrams">>. This > section > > would provide basic instructions for downloading source files from > > draw.io. > >3. 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. > >4. Here is the Jira for migrating/redoing existing diagrams > > 1. https://issues.apache.org/jira/browse/METRON-2099 > > > > We require a minimum of 72 hours for a vote, not typically including > > weekend days. I'd like to leave this vote open until Wednesday 5/8, 12PM > > EDT. Please vote +1, -1, or 0 to abstain, and also indicate if your vote > is > > binding or non-binding. > > --- > Thank you, > > James Sirota > PMC- Apache Metron > jsirota AT apache DOT org > >
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
+1 On May 2, 2019 at 21:18:21, Michael Miklavcic (michael.miklav...@gmail.com) wrote: Here's the latest discussion on the subject: https://lists.apache.org/thread.html/0aa2b0b9ed4a0f0b0d8bb018c618e62de196565f9af71f347e504076@%3Cdev.metron.apache.org%3E 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. 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. 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 as per section 2.4. Diagrams may be requested of PR submitters during review either as documentation or as an aid to the reviewer. Major features may also require a vote.">> 2. Under "2.4 Documentation" 1. New line item <<"Diagrams - We save architecture diagram source files in an xml format rendered by draw.io (instructions below). This is the free tool of choice that we've agreed to use for exchanging diagrams and their source files in Metron.">> 2. New line item >. This section would provide basic instructions for downloading source files from draw.io. 3. 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. 4. Here is the Jira for migrating/redoing existing diagrams 1. https://issues.apache.org/jira/browse/METRON-2099 We require a minimum of 72 hours for a vote, not typically including weekend days. I'd like to leave this vote open until Wednesday 5/8, 12PM EDT. Please vote +1, -1, or 0 to abstain, and also indicate if your vote is binding or non-binding.
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
i am ok with it as long as we are not forcing people to buy stuff 02.05.2019, 18:18, "Michael Miklavcic" : > Here's the latest discussion on the subject: > https://lists.apache.org/thread.html/0aa2b0b9ed4a0f0b0d8bb018c618e62de196565f9af71f347e504076@%3Cdev.metron.apache.org%3E > > 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. 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. 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 as per section 2.4. Diagrams may be requested of PR > submitters during review either as documentation or as an aid to the > reviewer. Major features may also require a vote.">> > 2. Under "2.4 Documentation" > 1. New line item <<"Diagrams - We save architecture diagram source > files in an xml format rendered by draw.io (instructions below). This > is the free tool of choice that we've agreed to use for exchanging > diagrams and their source files in Metron.">> > 2. New line item < "/images-source" and rendered diagrams and images belong in > "/images." > 3. New subsection <<"Creating and Modifying Diagrams">>. This section > would provide basic instructions for downloading source files from > draw.io. > 3. 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. > 4. Here is the Jira for migrating/redoing existing diagrams > 1. https://issues.apache.org/jira/browse/METRON-2099 > > We require a minimum of 72 hours for a vote, not typically including > weekend days. I'd like to leave this vote open until Wednesday 5/8, 12PM > EDT. Please vote +1, -1, or 0 to abstain, and also indicate if your vote is > binding or non-binding. --- Thank you, James Sirota PMC- Apache Metron jsirota AT apache DOT org
[VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
Here's the latest discussion on the subject: https://lists.apache.org/thread.html/0aa2b0b9ed4a0f0b0d8bb018c618e62de196565f9af71f347e504076@%3Cdev.metron.apache.org%3E 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. 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. 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 as per section 2.4. Diagrams may be requested of PR submitters during review either as documentation or as an aid to the reviewer. Major features may also require a vote.">> 2. Under "2.4 Documentation" 1. New line item <<"Diagrams - We save architecture diagram source files in an xml format rendered by draw.io (instructions below). This is the free tool of choice that we've agreed to use for exchanging diagrams and their source files in Metron.">> 2. New line item >. This section would provide basic instructions for downloading source files from draw.io. 3. 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. 4. Here is the Jira for migrating/redoing existing diagrams 1. https://issues.apache.org/jira/browse/METRON-2099 We require a minimum of 72 hours for a vote, not typically including weekend days. I'd like to leave this vote open until Wednesday 5/8, 12PM EDT. Please vote +1, -1, or 0 to abstain, and also indicate if your vote is binding or non-binding.
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
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 > 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 >> 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 >> > 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
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
That works too On Fri, Apr 26, 2019, 12:20 PM Otto Fowler 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 > 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 > > 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
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
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 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 > 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 > >
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
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 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 > 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
Re: [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
- 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. - Existing diagrams, in order to be modified, will have to be converted to this format, there should be jiras for that 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 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
[VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
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
