metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Otto Fowler <ottobackwa...@gmail.com>
Subject Re: [DISCUSS] Dev guideline changes for architecture diagrams
Date Thu, 02 May 2019 22:16:36 GMT
+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 <ottobackwards@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
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message