metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Miklavcic <michael.miklav...@gmail.com>
Subject [VOTE] Update dev guidelines with format for sharing architecture source files and rendered images
Date Fri, 03 May 2019 01:18:00 GMT
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 <<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


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.

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