1. +1 with a guideline: If code and docs share a JIRA ticket, the ticket cannot (or at least should not) be closed until both parts are complete. In some cases both tasks finish around the same time, so a shared ticket is fine.
But there are cases where code is completed before docs (as with bug fixes where the developer doesn't realize there's a doc impact until after the code has been repaired) or where docs finish before code (as is historically true with deprecations). In cases where the two tasks don't finish near the same time, I prefer separate tickets with a connection in JIRA. This can usually take the form of a doc ticket labeled as a 'subtask' to the code ticket. That way neither effort prevents the other from declaring victory and moving forward. 2. +1 3. +1 On Tue, Oct 25, 2016 at 6:14 PM, William Markito <wmark...@pivotal.io> wrote: > 1. +1 > 2. +1 - Reason and common sense should apply... > 3. +1 > > On Tue, Oct 25, 2016 at 6:03 PM, Joey McAllister <jmcallis...@pivotal.io> > wrote: > > > Thanks for kicking this off, Karen! > > > > 1. +1 - I like the idea of making documentation part of the requirements > > for issues that need it. Is it better in these cases to use the primary > > ticket or to create a new subticket associated with the primary one? > > > > 2. +1 - I agree that reviews should be on a case-by-case basis. Since the > > community has committers/contributors who specialize in technical > > documentation, I'd hope that those docs specialists would make themselves > > available for such reviews. And, on the flip side, I'd hope that anyone > > focused on adding/editing documentation based on new/changed code would > > seek the review of the developer who worked on the code. And, yes > > (connected to #3 below), I think small changes might not need reviews at > > all. > > > > 3. +1 > > > > On Tue, Oct 25, 2016 at 5:47 PM Karen Miller <kmil...@apache.org> wrote: > > > > > With our documentation now in the same repository as the code, there > are > > > now > > > some doc-related issues that could use some community consensus. Here > are > > > some of my opinions to start the discussion. > > > > > > 1. Create new JIRA tickets for each documentation task, or use the > > existing > > > ticket under > > > which the code is committed for the documentation task? > > > > > > I'd like to see a combination of both, but use the existing ticket > > > wherever > > > possible. By using the same ticket as the code, the documentation > effort > > is > > > less > > > likely to be forgotten. I certainly think that when a new property is > > > introduced, > > > or a default value is changed, the same ticket can be used. > > > > > > I think that for large, and new efforts (in the documentation), new > > > tickets are the > > > way to go. > > > > > > 2. Do we need a review effort for all documentation tasks? > > > > > > My opinion: no, not for everything. The bigger the changes, the > more > > > likely that > > > a review is warranted. > > > > > > 3. Do we need a new JIRA ticket for each very little documentation > > change? > > > > > > On this question, my strong opinion is no, we don't need distinct > > JIRAs. > > > I'd like to propose that we use a single ticket per release that > > > all typo fixes and really small changes are committed under. No > > > reviews needed. We won't end up with dozens of tickets, each for a tiny > > > change that really needs no community discussion. If the ticket > becomes > > > abused, > > > we can revisit the topic. > > > > > > I've already created https://issues.apache.org/ > jira/browse/GEODE-2036 > > > for > > > just this purpose, as I have a typo that I want to fix. If no one > > objects, > > > we can > > > use this ticket for all tiny fixes that go with Geode 1.1.0. > > > > > > > > > -- > > ~/William >
