You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cassandra.apache.org by Ekaterina Dimitrova <e....@gmail.com> on 2020/08/01 00:23:05 UTC
Re: [DISCUSS] CASSANDRA Jira modification - add Doc Impact field
+1, both author and reviewer have to ensure that documentation is not
missed, not less important than any code. Bad documentation can make a
great feature looking really bad. I know “test and documentation” is
already mandatory so the only thing that appears now on my mind is to
remind everyone not to forget it and to keep on reminding each other, I
guess.
Or maybe to add some template with a couple of specific questions that need
to be answered?
Example: “Does this patch require a new documentation page?
Does this patch require documentation update?
Please verify any related documentation is clear enough for the users”
Maybe it will be a bit too much but if the required field is not enough and
if we think something more needs to be done...
Best regards,
Ekaterina
On Fri, 31 Jul 2020 at 19:56, Erick Ramirez <er...@datastax.com>
wrote:
> >
> > and it appears to be required on "Submit Patch" - the problem is that
> > nobody really fills it out very well. Being mandatory is insufficient.
> >
>
> +1 I agree. Wherever this ends up in the workflow, I'd like to suggest that
> a reviewer verify that doc updates are *not* required as part of the "exit"
> criteria. Thoughts?
>
Re: [DISCUSS] CASSANDRA Jira modification - add Doc Impact field
Posted by Ekaterina Dimitrova <e....@gmail.com>.
A refresh of the checklist sounds good to me and I think it corresponds
well to all the changes and improvements happening lately on the project.
I am not a committer so I will refrain from any big comments but as a
software engineer, I would say I am well aware and a fan of the practices
you shared.
Best regards,
Ekaterina
On Sun, 2 Aug 2020 at 14:38, Mick Semb Wever <mc...@apache.org> wrote:
> > > > Or maybe to add some template with a couple of specific questions
> that
> > > > need to be answered?
> > >
> > >
> > > Agreed.
> > > We do have
> > > https://cassandra.apache.org/doc/latest/development/how_to_review.html
> > >
> > > We should have a summary of and link to that page in the JIRA "-->
> > > Ready to Commit" transition.
> > > And maybe even make mention of it in the "--> Start Review" transition.
> >
> > Even better, reference to the full checklist sounds good to me
> > +1
>
>
> We can also improve that Review doc…
>
> IMHO there's a lot we can take from
> https://google.github.io/eng-practices/review/
>
> For example, our documentation doesn't address
> - Picking the Best Reviewers (from competence to collaboration across
> company
> silos)
> - Design & Complexity (it is only briefly touched on under 'General', also
> could extend to processes-at-large for bugs vs improvements vs CEPs)
> - Commit message and CHANGES.txt
> - Review communication, from etiquette to where can the review happen (in
> the jira ticket, GH commit messages, GH PRs)
> - How to resolve/escalate disagreements, challenges, disappearing people,
> etc
>
> The first point about "who reviews" has been touched on in other threads
> related to project governance.
>
> I suspect a lot of the current Review doc can be first expanded to be more
> thorough with our current practices. Beyond that is there anyone in the
> google doc (that is relevant, e.g. not in-person reviews) that anyone
> objects to?
>
Re: [DISCUSS] CASSANDRA Jira modification - add Doc Impact field
Posted by Mick Semb Wever <mc...@apache.org>.
> > > Or maybe to add some template with a couple of specific questions that
> > > need to be answered?
> >
> >
> > Agreed.
> > We do have
> > https://cassandra.apache.org/doc/latest/development/how_to_review.html
> >
> > We should have a summary of and link to that page in the JIRA "-->
> > Ready to Commit" transition.
> > And maybe even make mention of it in the "--> Start Review" transition.
>
> Even better, reference to the full checklist sounds good to me
> +1
We can also improve that Review doc…
IMHO there's a lot we can take from
https://google.github.io/eng-practices/review/
For example, our documentation doesn't address
- Picking the Best Reviewers (from competence to collaboration across company
silos)
- Design & Complexity (it is only briefly touched on under 'General', also
could extend to processes-at-large for bugs vs improvements vs CEPs)
- Commit message and CHANGES.txt
- Review communication, from etiquette to where can the review happen (in
the jira ticket, GH commit messages, GH PRs)
- How to resolve/escalate disagreements, challenges, disappearing people,
etc
The first point about "who reviews" has been touched on in other threads
related to project governance.
I suspect a lot of the current Review doc can be first expanded to be more
thorough with our current practices. Beyond that is there anyone in the
google doc (that is relevant, e.g. not in-person reviews) that anyone
objects to?
Re: [DISCUSS] CASSANDRA Jira modification - add Doc Impact field
Posted by Ekaterina Dimitrova <e....@gmail.com>.
Even better, reference to the full checklist sounds good to me
+1
On Sat, 1 Aug 2020 at 4:42, Mick Semb Wever <mc...@apache.org> wrote:
> > Or maybe to add some template with a couple of specific questions that
> need
> > to be answered?
>
>
> Agreed.
> We do have
> https://cassandra.apache.org/doc/latest/development/how_to_review.html
>
> We should have a summary of and link to that page in the JIRA "-->
> Ready to Commit" transition.
> And maybe even make mention of it in the "--> Start Review" transition.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
> For additional commands, e-mail: dev-help@cassandra.apache.org
>
>
Re: [DISCUSS] CASSANDRA Jira modification - add Doc Impact field
Posted by Mick Semb Wever <mc...@apache.org>.
> Or maybe to add some template with a couple of specific questions that need
> to be answered?
Agreed.
We do have https://cassandra.apache.org/doc/latest/development/how_to_review.html
We should have a summary of and link to that page in the JIRA "-->
Ready to Commit" transition.
And maybe even make mention of it in the "--> Start Review" transition.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cassandra.apache.org
For additional commands, e-mail: dev-help@cassandra.apache.org