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