Tentatively agreed on further clarification of what we consider in/out of
scope for documentation re: document something that wasn't documented
before. Ryan, can you give a quick summary of what you *have* added/updated
in documentation on this PR vs what you want to leave out?

My initial concern in punting on docs right now is that part of what made
this PR/task more challenging in the first place was not having
documentation. We risk losing context and detail again if we don't do this
immediately. Would it be reasonable to split it up as follows?:

   1. Additional overarching documentation feels out of scope - make it a
   follow on (see comments below).
   2. Adding documentation to our existing README's and java code comments
   that describe the new/modified functionality should be in scope because
   it's part of the unit of work. I expect that a developer should be able to
   look at the code, tests, comments, and README's and understand how this
   code functions without having to start from scratch.

The way we've handled follow-on work before, at least as far as feature
branches are concerned, was to create Jiras and link them to the
appropriate discussions for context. Maybe we can take that one step
further and do the release manager a favor by also labeling the
required/requested release on the Jira as a gating factor. This follows our
pattern for intermittent test failure reporting, e.g.

I'm also in favor of continuing to document architecture and technical
details as part of the code base as Ryan and Jon have suggested. I think we
should have an "architecture.md" in metron root that replaces this -
and covers the broad architecture with links to the appropriate modules for
detail. Minimally, it would be nice if we had a simple diagram showing the
basic flow of data in Metron. I think we probably want an updated version
of this wiki entry from back in the day -


On Mon, Feb 25, 2019 at 7:18 AM Nick Allen <n...@nickallen.org> wrote:

> I don't think we should hold up this work to document something that wasn't
> previously documented.  A follow-on is sufficient.
> On Mon, Feb 25, 2019 at 8:50 AM Ryan Merriman <merrim...@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?
> >

Reply via email to