Ironically, those docs are inaccurate!
On 31/07/2020, 21:25, "Lorina Poland" <lor...@datastax.com> wrote:
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
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
For additional commands, e-mail: dev-h...@cassandra.apache.org
