metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nick Allen <n...@nickallen.org>
Subject Re: [DISCUSS] Architecture documentation
Date Mon, 25 Feb 2019 14:13:36 GMT
> Procedurally, do we have a way to ensure that any follow-on documentation happens
prior to a release (anything in the wiki, etc.)?

If someone thinks the code base needs X before the next release, then they
can bring up X during the release discussion.  We don't need additional
procedure around this.

On Mon, Feb 25, 2019 at 9:11 AM Zeolla@GMail.com <zeolla@gmail.com> wrote:

> 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