I was just working from this doc: https://cwiki.apache.org/confluence/display/CASSANDRA/JIRA+Workflow+Proposals
Test and Documentation Plan > A new required field containing free-form text field, required when > transitioning to 'In Progress'. > The intended purpose is to encourage explicit upfront consideration of the > work needed on these areas > either before or following commit. This may entail filing follow-up > tickets that need to be resolved before release, > or a brief statement on the tests that will be written, or simply 'n/a'. > This also provides a promise to hold implementors to before release, and a > point of discussion before a ticket lands. Now that you pointed it out, I do see the "Impacts" field. A search of: *Impacts in (Docs) and project in (Cassandra) and fixVersion in (4.0)* does turn up what I'm looking for in terms of knowing about tickets that require docs. The automation rule would still be nice, and could be triggered when Impacts = Docs. Thanks for the info, Benedict! Lorina Poland On Fri, Jul 31, 2020 at 1:10 PM Benedict Elliott Smith <bened...@apache.org> wrote: > > It is mandatory to move a ticket to "In Progress" > > I think you are mistaken; I have triple-checked, and it appears to be > required on "Submit Patch" - the problem is that nobody really fills it out > very well. Being mandatory is insufficient. > > Also, to clarify my earlier email, there already exists a field called > "Impacts" which includes "Docs" as an option to indicate there exists a > documentation impact to consider, mostly to support search. > > > On 31/07/2020, 20:51, "Lorina Poland" <lor...@datastax.com> wrote: > > I believe that the Test and Documentation Plan field is required too > early > in the progress for Documentation needs. It is mandatory to move a > ticket > to "In Progress". I suspect that, while a developer may say something > in > this field, they won't really be sure of the doc impact at that stage. > > I would find it useful to have a mandatory Doc Impact field before a > ticket > moves from "In Progress" to "Patch Available". The design and > implementation of the code work will be uppermost at that point, when > the > developer has finally made the code changes. > > I see tickets that have wonderful design docs early in the process. > But as > the work progresses, the design changes, and those changes are not > captured > in any summary manner. > > For instance, I'm currently working to rewrite audit logging ( > https://issues.apache.org/jira/browse/CASSANDRA-12151). Weeding > through 4 > years of comments and changes is challenging. If the developer had > marked > Doc Impact and perhaps written some Doc Notes right before "Patch > Available", I'd feel much more confident that I understand what the > submitted change is. For some development, I can look at the code and > figure out what it does. A topic like audit logging is likely to use > many > classes and touch on many items that I'm not familiar with nor be the > most > readable code. > > Lorina Poland > > > > > On Fri, Jul 31, 2020 at 12:35 PM Benedict Elliott Smith < > bened...@apache.org> > wrote: > > > Impacts -> Docs > > > > It's not mandatory, but we could perhaps consider making it so > somewhere > > in the workflow. Do you have a good suggestion for where? > > > > There's also "Test and Documentation Plan" which is already > mandatory. > > > > > > On 31/07/2020, 20:28, "Lorina Poland" <lor...@datastax.com> wrote: > > > > This morning, Caleb Rackliffe mentioned to me that > CASSANDRA-15907 > > involved > > some code work that has Documentation implications, just to let > me > > know. > > > > I'd like to propose a change to the Cassandra Jira system, to > include a > > field called "Doc Impact" that a developer could check if there > is > > accompanying documentation that should be written. It would help > with > > discovery, so that a corresponding _Documentation%Website_ Jira > ticket > > could be written for the work. > > > > At DataStax, I've gone even a step further and added an > automation rule > > that makes a copy of the original ticket if the Doc Impact field > is > > checked. I would love to have that as well, but would be happy > just > > for the > > Doc Impact field. If Doc Impact was mandatory when a ticket > moves from > > review to merge, for instance, that would be useful, too. > > > > Thanks, > > Lorina Poland > > > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org > > For additional commands, e-mail: dev-h...@cassandra.apache.org > > > > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org > For additional commands, e-mail: dev-h...@cassandra.apache.org > >
