metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Zeolla@GMail.com" <zeo...@gmail.com>
Subject Re: [DISCUSS] Architecture documentation
Date Mon, 25 Feb 2019 14:11:25 GMT
I agree, I think all docs should be kept in the code base.  I
opened METRON-714 ages ago to get the existing cwiki docs over to READMEs
as well.

I would also like to see us consider a more general/overview architecture,
or perhaps write each component's architecture in a way that it can be
composed into a higher level doc when generating the site-book.  Right now
the barrier to getting started with Metron is too high, and I think this
would make it slightly less imposing.  But this is slightly outside of the
scope of the current conversation.

Procedurally, do we have a way to ensure that any follow-on documentation
happens prior to a release (anything in the wiki, etc.)?  I'm fine with
splitting the commits generally.

Jon

On Mon, Feb 25, 2019 at 8:50 AM Ryan Merriman <merrimanr@gmail.com> wrote:

> Recently I submitted a PR <https://github.com/apache/metron/pull/1330>
> that
> introduces a large number of changes to a critical part of our code base.
> Reviewers feel like it is significant enough to document at an
> architectural level (and I agree).  There are a couple points I would like
> to clarify.
>
> Generally architectural documentation lives in the README of the
> appropriate module.  Do we want to continue documenting architecture here?
> I think it makes sense because it will be versioned along with the code.
> Just wanted to confirm there are no objections to continuing this practice.
>
> A reviewer suggested we could accept the PR as is and leave the
> architectural documentation as a follow on.  I think this makes sense
> because it can be tedious to maintain a large PR as other smaller commits
> are accepted into master.  An important requirement is the documentation
> follow on must be completed in a timely manner, before the next release.
> Are there any objections to doing it this way?
>
-- 

Jon Zeolla

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