You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@metron.apache.org by Michael Miklavcic <mi...@gmail.com> on 2019/05/02 00:12:31 UTC
[DISCUSS] Dev guideline changes for architecture diagrams
Picking up where things left off in the VOTE thread on the subject,
I'm presenting a revision to my original proposal below. I'd like to get
this signed off on before submitting it for another vote. Otto, picking up
where we left off, let me know if this looks good to you.
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. 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 <<Image and diagram source files belong in
"<module-name>/images-source" and rendered diagrams and images belong in
"<module-name>/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
- Original DISCUSS thread -
https://lists.apache.org/thread.html/3ae02f1e32044b1a7648899700d44611aefdab6caa09fb3196292425@%3Cdev.metron.apache.org%3E
- Original VOTE thread -
https://lists.apache.org/thread.html/c41dca65a46354c161d58caa7c79cfac6758f437b6638d12bd5c5622@%3Cdev.metron.apache.org%3E
Re: [DISCUSS] Dev guideline changes for architecture diagrams
Posted by Otto Fowler <ot...@gmail.com>.
+1, great job Mike
On May 2, 2019 at 18:06:28, Michael Miklavcic (michael.miklavcic@gmail.com)
wrote:
I thought it might be useful as a more general purpose bucket, and it's how
we refer to the image files in the site-book generation. Also, there may be
things that might not qualify as a diagram, but have some value. A few
README's use screenshots. Here's an example:
1.
https://github.com/apache/metron/blob/master/metron-deployment/Kerberos-ambari-setup.md
2.
https://github.com/apache/metron/tree/master/metron-deployment/readme-images
.
What do you think?
On Thu, May 2, 2019 at 5:19 AM Otto Fowler <ot...@gmail.com> wrote:
> I’m all set with this, but for one question, why image and image-source
as
> opposed to diagram and diagram source? Isn’t it more descriptive? Is
> there another reason ( like for doc gen )?
>
>
>
> On May 1, 2019 at 20:12:47, Michael Miklavcic (michael.miklavcic@gmail.com
> )
> wrote:
>
> Picking up where things left off in the VOTE thread on the subject,
> I'm presenting a revision to my original proposal below. I'd like to get
> this signed off on before submitting it for another vote. Otto, picking
up
> where we left off, let me know if this looks good to you.
>
> 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. 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 <<Image and diagram source files belong in
> "<module-name>/images-source" and rendered diagrams and images belong in
> "<module-name>/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
>
>
>
> - Original DISCUSS thread -
>
>
https://lists.apache.org/thread.html/3ae02f1e32044b1a7648899700d44611aefdab6caa09fb3196292425@%3Cdev.metron.apache.org%3E
> - Original VOTE thread -
>
>
https://lists.apache.org/thread.html/c41dca65a46354c161d58caa7c79cfac6758f437b6638d12bd5c5622@%3Cdev.metron.apache.org%3E
>
Re: [DISCUSS] Dev guideline changes for architecture diagrams
Posted by Michael Miklavcic <mi...@gmail.com>.
I thought it might be useful as a more general purpose bucket, and it's how
we refer to the image files in the site-book generation. Also, there may be
things that might not qualify as a diagram, but have some value. A few
README's use screenshots. Here's an example:
1.
https://github.com/apache/metron/blob/master/metron-deployment/Kerberos-ambari-setup.md
2.
https://github.com/apache/metron/tree/master/metron-deployment/readme-images
.
What do you think?
On Thu, May 2, 2019 at 5:19 AM Otto Fowler <ot...@gmail.com> wrote:
> I’m all set with this, but for one question, why image and image-source as
> opposed to diagram and diagram source? Isn’t it more descriptive? Is
> there another reason ( like for doc gen )?
>
>
>
> On May 1, 2019 at 20:12:47, Michael Miklavcic (michael.miklavcic@gmail.com
> )
> wrote:
>
> Picking up where things left off in the VOTE thread on the subject,
> I'm presenting a revision to my original proposal below. I'd like to get
> this signed off on before submitting it for another vote. Otto, picking up
> where we left off, let me know if this looks good to you.
>
> 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. 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 <<Image and diagram source files belong in
> "<module-name>/images-source" and rendered diagrams and images belong in
> "<module-name>/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
>
>
>
> - Original DISCUSS thread -
>
> https://lists.apache.org/thread.html/3ae02f1e32044b1a7648899700d44611aefdab6caa09fb3196292425@%3Cdev.metron.apache.org%3E
> - Original VOTE thread -
>
> https://lists.apache.org/thread.html/c41dca65a46354c161d58caa7c79cfac6758f437b6638d12bd5c5622@%3Cdev.metron.apache.org%3E
>
Re: [DISCUSS] Dev guideline changes for architecture diagrams
Posted by Otto Fowler <ot...@gmail.com>.
I’m all set with this, but for one question, why image and image-source as
opposed to diagram and diagram source? Isn’t it more descriptive? Is
there another reason ( like for doc gen )?
On May 1, 2019 at 20:12:47, Michael Miklavcic (michael.miklavcic@gmail.com)
wrote:
Picking up where things left off in the VOTE thread on the subject,
I'm presenting a revision to my original proposal below. I'd like to get
this signed off on before submitting it for another vote. Otto, picking up
where we left off, let me know if this looks good to you.
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. 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 <<Image and diagram source files belong in
"<module-name>/images-source" and rendered diagrams and images belong in
"<module-name>/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
- Original DISCUSS thread -
https://lists.apache.org/thread.html/3ae02f1e32044b1a7648899700d44611aefdab6caa09fb3196292425@%3Cdev.metron.apache.org%3E
- Original VOTE thread -
https://lists.apache.org/thread.html/c41dca65a46354c161d58caa7c79cfac6758f437b6638d12bd5c5622@%3Cdev.metron.apache.org%3E