metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Miklavcic <michael.miklav...@gmail.com>
Subject Re: [DISCUSS] Dev guideline changes for architecture diagrams
Date Thu, 02 May 2019 22:06:05 GMT
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