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 19:45:27 GMT
I disagree, I would hold up a code change that has no documentation/no
plans for documentation.  It's also very possible that, if documentation
was to come later on a specific workstream, it could get forgotten.  It
kind of breaks the review process IMO unless there's a compensating
control, such as a JIRA with a specific tag and a reminder in the release
process to check for that.

Jon

On Mon, Feb 25, 2019 at 9:14 AM Nick Allen <nick@nickallen.org> wrote:

> > 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
> >
>
-- 

Jon Zeolla

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