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 <n...@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 zeo...@gmail.com <zeo...@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 <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? > > > > > -- > > > > Jon Zeolla > > > -- Jon Zeolla
