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