Re: [DISCUSS] Architecture documentation

And just to be clear, this is just a continuation of the discussion in this thread. This is not in any way a blocker for Ryan's PR, of course. On Tue, Feb 26, 2019 at 1:44 PM Nick Allen wrote: > > We could also enhance > "metron/dev-utilities/release-utils/validate-jira-for-release" so that it

Re: [DISCUSS] Architecture documentation

We could also enhance "metron/dev-utilities/release-utils/validate-jira-for-release" so that it spits out a warning for any JIRAs that are marked "Next + 1", but don't have a record in the commit history. That would at least be a reminder that the JIRA needs some follow-up. On Mon, Feb 25, 20

Re: [DISCUSS] Architecture documentation

Sorry for the delay here. Yup I'm good with where this ended up, thanks! Jon On Tue, Feb 26, 2019 at 10:21 AM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > @Jon - I think this DISCUSS thread is the last gating factor for getting > this PR in, are you ok with the prescribed approach

Re: [DISCUSS] Architecture documentation

@Jon - I think this DISCUSS thread is the last gating factor for getting this PR in, are you ok with the prescribed approach here? i.e. Ryan has already done a lot of clarification and expansion in the README's and code comments, and the follow-on will be creating a separate architecture document i

Re: [DISCUSS] Architecture documentation

Re: Labeling in Jira, I'm fine with having a be "Next + 1" from a release management perspective, but I'd still consider at least taking action on followup to be the relevant party's responsibility (implementer or whatever the case may be). We probably should have a more clear way to tag things li

Re: [DISCUSS] Architecture documentation

I really like the idea of architecture.md -> **/architecture.md. We overall do not have javadoc in a lot of areas, and could maybe start working on it as we go and think about asking for it in reviews. We are also missing the Parser Programmer’s Guide, how to add a parser to the metron system/inst

Re: [DISCUSS] Architecture documentation

I feel like the code itself is pretty well documented. I updated existing javadocs and added javadocs to classes that didn't have them before this PR. In my opinion the level of documentation for these classes has increased significantly. On Mon, Feb 25, 2019 at 1:52 PM Michael Miklavcic < micha

Re: [DISCUSS] Architecture documentation

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

Re: [DISCUSS] Architecture documentation

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 a

Re: [DISCUSS] Architecture documentation

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 wrote: > Recently I submitted a PR > that > introduces a large number of chang

Re: [DISCUSS] Architecture documentation

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

Re: [DISCUSS] Architecture documentation

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 compose

[DISCUSS] Architecture documentation

Recently I submitted a PR 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.