Re: [DISCUSS] Architecture documentation

2019-02-25 Thread Justin Leet
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

Re: [DISCUSS] Architecture documentation

2019-02-25 Thread Otto Fowler
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

Re: [DISCUSS] Charset PR merge effects

2019-02-25 Thread Michael Miklavcic
Justin, I like your proposal. I just had a couple thoughts that I think are worth pointing out. I'm not 100% clear about this point, but I don't believe we currently handle the possibility of various external data sources with heterogeneous encoding schemes in our Kafka topics. As it stands, I

Re: [DISCUSS] Architecture documentation

2019-02-25 Thread Ryan Merriman
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 <

Re: [DISCUSS] Architecture documentation

2019-02-25 Thread Michael Miklavcic
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

2019-02-25 Thread zeo...@gmail.com
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

Re: [DISCUSS] Architecture documentation

2019-02-25 Thread Nick Allen
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

Re: [DISCUSS] Architecture documentation

2019-02-25 Thread Nick Allen
> 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

Re: [DISCUSS] Architecture documentation

2019-02-25 Thread zeo...@gmail.com
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

[DISCUSS] Architecture documentation

2019-02-25 Thread Ryan Merriman
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