You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ozone.apache.org by Hemant Kumar <he...@apache.org> on 2023/09/21 16:53:31 UTC
Ozone Jira and PR guidelines
Hi Ozone Community,
As we discussed in the last ozone community meeting about Ozone jiras and
PRs not having enough information/details. Which makes it harder to
understand when people outside the project look at them. Hence to make it
better, I'm proposing the following guideline.
Please take a look and let me know your thoughts. Once we are in agreement,
I'll add them to Ozone onboarding wiki.
*Jira description guideline:*
* Title: Title should be a one liner stating the problem.
* Description:
* What is the problem? Is it a feature, improvement or bug? Add as
many details as possible and related design doc and discussion.
* For new features, add as many details as possible. If it is part of
the big feature, attach parent jira.
* For improvement, add the value it will bring. Is it an optimization,
code simplification or something else?
* For bugs, add steps to reproduce it. Where the root cause is unknown
and needs investigation, it would be great to update the jira description
or add the summary once the root cause is identified.
* Jira examples:
* https://issues.apache.org/jira/browse/HDDS-9272
* https://issues.apache.org/jira/browse/HDDS-9322
* https://issues.apache.org/jira/browse/HDDS-9291
* https://issues.apache.org/jira/browse/HDDS-8940
* https://issues.apache.org/jira/browse/HDDS-9282
*PR description guideline:*
* Title: Title should provide a one sentence overview of the purpose of the
PR.
* Description:
* What changes are proposed in the PR? and Why?
* Provide as much context and rationale for the pull request as
possible. It could be copy-paste from the jira's description if the jira is
well defined.
* If it is complex code, describe the approach used to solve the issue.
If possible attach design doc, issue investigation, github discussion, etc.
* Testing:
* How is the code tested?
* Attach CD/CI run on the personal git repo.
* PR examples:
* https://github.com/apache/ozone/pull/3980
* https://github.com/apache/ozone/pull/5265
* https://github.com/apache/ozone/pull/4701
* https://github.com/apache/ozone/pull/5283
* https://github.com/apache/ozone/pull/5300
* https://github.com/apache/ozone/pull/5301
Thanks,
Hemant
Re: Ozone Jira and PR guidelines
Posted by Hemant Kumar <he...@apache.org>.
Thanks everyone for the valuable inputs. As I can see, all of us agree that
we need some sort of guidelines.
As Sid suggested, I created PR: https://github.com/apache/ozone/pull/5372
updating contribution and pull request template.
Please take a look and provide feedback.
@ayushtkn, as you said, closing tickets (not having much details) is a
community decision. We can come back to it later once we have guidelines in
place.
@weichiu, It is a good idea to create something like OIP (Ozone improvement
proposal) but I think we are far from there. I'll suggest starting with a
simple guideline (as I mentioned above) first and over time iteratively
improving it to reach OIP.
Thanks,
Hemant
On Thu, Sep 21, 2023 at 2:37 PM Wei-Chiu Chuang <we...@apache.org> wrote:
> Might be irrelevant but I just want to point out that other open source
> projects have more stringent requirements when it comes to filing a jira.
>
> Infact, Kafka has KIP (Kafka Improvement Proposal) Yunikorn has YIP
> (Yunikorn Improvement Proposal) and the proposers need to have sufficient
> support (which means much more communication) before moving forward with
> the development. Not saying we need to have an OIP, but having that extra
> level of communication and consensus seems healthy.
>
> On Thu, Sep 21, 2023 at 9:54 AM Hemant Kumar <he...@apache.org> wrote:
>
> > Hi Ozone Community,
> > As we discussed in the last ozone community meeting about Ozone jiras and
> > PRs not having enough information/details. Which makes it harder to
> > understand when people outside the project look at them. Hence to make it
> > better, I'm proposing the following guideline.
> > Please take a look and let me know your thoughts. Once we are in
> agreement,
> > I'll add them to Ozone onboarding wiki.
> >
> > *Jira description guideline:*
> > * Title: Title should be a one liner stating the problem.
> > * Description:
> > * What is the problem? Is it a feature, improvement or bug? Add as
> > many details as possible and related design doc and discussion.
> > * For new features, add as many details as possible. If it is part of
> > the big feature, attach parent jira.
> > * For improvement, add the value it will bring. Is it an
> optimization,
> > code simplification or something else?
> > * For bugs, add steps to reproduce it. Where the root cause is
> unknown
> > and needs investigation, it would be great to update the jira description
> > or add the summary once the root cause is identified.
> > * Jira examples:
> > * https://issues.apache.org/jira/browse/HDDS-9272
> > * https://issues.apache.org/jira/browse/HDDS-9322
> > * https://issues.apache.org/jira/browse/HDDS-9291
> > * https://issues.apache.org/jira/browse/HDDS-8940
> > * https://issues.apache.org/jira/browse/HDDS-9282
> >
> > *PR description guideline:*
> > * Title: Title should provide a one sentence overview of the purpose of
> the
> > PR.
> > * Description:
> > * What changes are proposed in the PR? and Why?
> > * Provide as much context and rationale for the pull request as
> > possible. It could be copy-paste from the jira's description if the jira
> is
> > well defined.
> > * If it is complex code, describe the approach used to solve the
> issue.
> > If possible attach design doc, issue investigation, github discussion,
> etc.
> > * Testing:
> > * How is the code tested?
> > * Attach CD/CI run on the personal git repo.
> >
> > * PR examples:
> > * https://github.com/apache/ozone/pull/3980
> > * https://github.com/apache/ozone/pull/5265
> > * https://github.com/apache/ozone/pull/4701
> > * https://github.com/apache/ozone/pull/5283
> > * https://github.com/apache/ozone/pull/5300
> > * https://github.com/apache/ozone/pull/5301
> >
> > Thanks,
> > Hemant
> >
>
Re: Ozone Jira and PR guidelines
Posted by Wei-Chiu Chuang <we...@apache.org>.
Might be irrelevant but I just want to point out that other open source
projects have more stringent requirements when it comes to filing a jira.
Infact, Kafka has KIP (Kafka Improvement Proposal) Yunikorn has YIP
(Yunikorn Improvement Proposal) and the proposers need to have sufficient
support (which means much more communication) before moving forward with
the development. Not saying we need to have an OIP, but having that extra
level of communication and consensus seems healthy.
On Thu, Sep 21, 2023 at 9:54 AM Hemant Kumar <he...@apache.org> wrote:
> Hi Ozone Community,
> As we discussed in the last ozone community meeting about Ozone jiras and
> PRs not having enough information/details. Which makes it harder to
> understand when people outside the project look at them. Hence to make it
> better, I'm proposing the following guideline.
> Please take a look and let me know your thoughts. Once we are in agreement,
> I'll add them to Ozone onboarding wiki.
>
> *Jira description guideline:*
> * Title: Title should be a one liner stating the problem.
> * Description:
> * What is the problem? Is it a feature, improvement or bug? Add as
> many details as possible and related design doc and discussion.
> * For new features, add as many details as possible. If it is part of
> the big feature, attach parent jira.
> * For improvement, add the value it will bring. Is it an optimization,
> code simplification or something else?
> * For bugs, add steps to reproduce it. Where the root cause is unknown
> and needs investigation, it would be great to update the jira description
> or add the summary once the root cause is identified.
> * Jira examples:
> * https://issues.apache.org/jira/browse/HDDS-9272
> * https://issues.apache.org/jira/browse/HDDS-9322
> * https://issues.apache.org/jira/browse/HDDS-9291
> * https://issues.apache.org/jira/browse/HDDS-8940
> * https://issues.apache.org/jira/browse/HDDS-9282
>
> *PR description guideline:*
> * Title: Title should provide a one sentence overview of the purpose of the
> PR.
> * Description:
> * What changes are proposed in the PR? and Why?
> * Provide as much context and rationale for the pull request as
> possible. It could be copy-paste from the jira's description if the jira is
> well defined.
> * If it is complex code, describe the approach used to solve the issue.
> If possible attach design doc, issue investigation, github discussion, etc.
> * Testing:
> * How is the code tested?
> * Attach CD/CI run on the personal git repo.
>
> * PR examples:
> * https://github.com/apache/ozone/pull/3980
> * https://github.com/apache/ozone/pull/5265
> * https://github.com/apache/ozone/pull/4701
> * https://github.com/apache/ozone/pull/5283
> * https://github.com/apache/ozone/pull/5300
> * https://github.com/apache/ozone/pull/5301
>
> Thanks,
> Hemant
>
Re: Ozone Jira and PR guidelines
Posted by Uma Maheswara Rao Gangumalla <um...@gmail.com>.
Thanks Ayush for your insightful thoughts.
I agree most of us fall into that "No Description JIRA" category :-). That
trend is more in branch developments especially.
>Though I am not very much in favour of closing tickets right away
based on discussions in Community sync. The contributor might be a
newbie, he might be genuinely not aware of the project policies, he
might not feel welcome if we do this.
It depends how we add a closing comment. User's will have a chance to
re-open any time. If the closing comment says something like "Please refer
to PR/Jira guide lines for adding description and feel free to reopen once
you are prepared with description for this JIRA", I would check and reopen
with details. I would welcome some activity on JIRA than not moving
anywhere.
Thanks Hemant for driving this.
Regards,
Uma
On Thu, Sep 21, 2023 at 1:07 PM Ayush Saxena <ay...@gmail.com> wrote:
> Makes sense to have policies around Jiras & PR, Having proper
> descriptions & linking the related tickets and stuff like that.
>
> Though I am not very much in favour of closing tickets right away
> based on discussions in Community sync. The contributor might be a
> newbie, he might be genuinely not aware of the project policies, he
> might not feel welcome if we do this.
>
> Maybe dropping a message, hey, can you fill up the relevant details,
> can read this doc for details around the process & then if they still
> don't do that it makes sense to close the ticket or if someone is a
> regular offender despite being told a couple of times.
>
> On a lighter note, yes, filling the description box is really
> important but we shouldn't treat it as a sin, I am pretty sure almost
> all of us who have been around for a couple of years in the opensource
> world would have done that some time in the past.
>
> On a quick search these are the tickets in Ozone with empty
> description, the count is 763 [1], and I tried to put all of our names
> as the assignee and found we all including me have tickets without
> description, can play with the filter. Not pointing anyone, this shows
> me as assignee with 17 ticket across all projects without description,
> with latest in 2023 itself, So, I myself guilty :-P
>
> Making policies & then educating people does make sense to me, but no
> objections from me if the community decides to be strict.
>
> Good Luck!!! Thanx Hemant for starting the thread!!!
>
> -Ayush
>
>
> [1]
> https://issues.apache.org/jira/issues/?jql=project%20%3D%20HDDS%20AND%20description%20is%20EMPTY
>
> On Fri, 22 Sept 2023 at 00:36, Uma Maheswara Rao Gangumalla
> <um...@gmail.com> wrote:
> >
> > Thank you Hemant for starting the discussion on JIRA and PR descriptions.
> > Also reviewers should step up to check the JIRA/PR descriptions as well
> > without biased understanding of the JIRA.
> >
> > We are doing JIRA scrub in community syncs and if we notice JIRAs without
> > descriptions we can close them right away.
> >
> > Regards,
> > Uma
> >
> > On Thu, Sep 21, 2023 at 9:55 AM Hemant Kumar <he...@apache.org> wrote:
> >
> > > Hi Ozone Community,
> > > As we discussed in the last ozone community meeting about Ozone jiras
> and
> > > PRs not having enough information/details. Which makes it harder to
> > > understand when people outside the project look at them. Hence to make
> it
> > > better, I'm proposing the following guideline.
> > > Please take a look and let me know your thoughts. Once we are in
> agreement,
> > > I'll add them to Ozone onboarding wiki.
> > >
> > > *Jira description guideline:*
> > > * Title: Title should be a one liner stating the problem.
> > > * Description:
> > > * What is the problem? Is it a feature, improvement or bug? Add as
> > > many details as possible and related design doc and discussion.
> > > * For new features, add as many details as possible. If it is part
> of
> > > the big feature, attach parent jira.
> > > * For improvement, add the value it will bring. Is it an
> optimization,
> > > code simplification or something else?
> > > * For bugs, add steps to reproduce it. Where the root cause is
> unknown
> > > and needs investigation, it would be great to update the jira
> description
> > > or add the summary once the root cause is identified.
> > > * Jira examples:
> > > * https://issues.apache.org/jira/browse/HDDS-9272
> > > * https://issues.apache.org/jira/browse/HDDS-9322
> > > * https://issues.apache.org/jira/browse/HDDS-9291
> > > * https://issues.apache.org/jira/browse/HDDS-8940
> > > * https://issues.apache.org/jira/browse/HDDS-9282
> > >
> > > *PR description guideline:*
> > > * Title: Title should provide a one sentence overview of the purpose
> of the
> > > PR.
> > > * Description:
> > > * What changes are proposed in the PR? and Why?
> > > * Provide as much context and rationale for the pull request as
> > > possible. It could be copy-paste from the jira's description if the
> jira is
> > > well defined.
> > > * If it is complex code, describe the approach used to solve the
> issue.
> > > If possible attach design doc, issue investigation, github discussion,
> etc.
> > > * Testing:
> > > * How is the code tested?
> > > * Attach CD/CI run on the personal git repo.
> > >
> > > * PR examples:
> > > * https://github.com/apache/ozone/pull/3980
> > > * https://github.com/apache/ozone/pull/5265
> > > * https://github.com/apache/ozone/pull/4701
> > > * https://github.com/apache/ozone/pull/5283
> > > * https://github.com/apache/ozone/pull/5300
> > > * https://github.com/apache/ozone/pull/5301
> > >
> > > Thanks,
> > > Hemant
> > >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@ozone.apache.org
> For additional commands, e-mail: dev-help@ozone.apache.org
>
>
Re: Ozone Jira and PR guidelines
Posted by Ayush Saxena <ay...@gmail.com>.
Makes sense to have policies around Jiras & PR, Having proper
descriptions & linking the related tickets and stuff like that.
Though I am not very much in favour of closing tickets right away
based on discussions in Community sync. The contributor might be a
newbie, he might be genuinely not aware of the project policies, he
might not feel welcome if we do this.
Maybe dropping a message, hey, can you fill up the relevant details,
can read this doc for details around the process & then if they still
don't do that it makes sense to close the ticket or if someone is a
regular offender despite being told a couple of times.
On a lighter note, yes, filling the description box is really
important but we shouldn't treat it as a sin, I am pretty sure almost
all of us who have been around for a couple of years in the opensource
world would have done that some time in the past.
On a quick search these are the tickets in Ozone with empty
description, the count is 763 [1], and I tried to put all of our names
as the assignee and found we all including me have tickets without
description, can play with the filter. Not pointing anyone, this shows
me as assignee with 17 ticket across all projects without description,
with latest in 2023 itself, So, I myself guilty :-P
Making policies & then educating people does make sense to me, but no
objections from me if the community decides to be strict.
Good Luck!!! Thanx Hemant for starting the thread!!!
-Ayush
[1] https://issues.apache.org/jira/issues/?jql=project%20%3D%20HDDS%20AND%20description%20is%20EMPTY
On Fri, 22 Sept 2023 at 00:36, Uma Maheswara Rao Gangumalla
<um...@gmail.com> wrote:
>
> Thank you Hemant for starting the discussion on JIRA and PR descriptions.
> Also reviewers should step up to check the JIRA/PR descriptions as well
> without biased understanding of the JIRA.
>
> We are doing JIRA scrub in community syncs and if we notice JIRAs without
> descriptions we can close them right away.
>
> Regards,
> Uma
>
> On Thu, Sep 21, 2023 at 9:55 AM Hemant Kumar <he...@apache.org> wrote:
>
> > Hi Ozone Community,
> > As we discussed in the last ozone community meeting about Ozone jiras and
> > PRs not having enough information/details. Which makes it harder to
> > understand when people outside the project look at them. Hence to make it
> > better, I'm proposing the following guideline.
> > Please take a look and let me know your thoughts. Once we are in agreement,
> > I'll add them to Ozone onboarding wiki.
> >
> > *Jira description guideline:*
> > * Title: Title should be a one liner stating the problem.
> > * Description:
> > * What is the problem? Is it a feature, improvement or bug? Add as
> > many details as possible and related design doc and discussion.
> > * For new features, add as many details as possible. If it is part of
> > the big feature, attach parent jira.
> > * For improvement, add the value it will bring. Is it an optimization,
> > code simplification or something else?
> > * For bugs, add steps to reproduce it. Where the root cause is unknown
> > and needs investigation, it would be great to update the jira description
> > or add the summary once the root cause is identified.
> > * Jira examples:
> > * https://issues.apache.org/jira/browse/HDDS-9272
> > * https://issues.apache.org/jira/browse/HDDS-9322
> > * https://issues.apache.org/jira/browse/HDDS-9291
> > * https://issues.apache.org/jira/browse/HDDS-8940
> > * https://issues.apache.org/jira/browse/HDDS-9282
> >
> > *PR description guideline:*
> > * Title: Title should provide a one sentence overview of the purpose of the
> > PR.
> > * Description:
> > * What changes are proposed in the PR? and Why?
> > * Provide as much context and rationale for the pull request as
> > possible. It could be copy-paste from the jira's description if the jira is
> > well defined.
> > * If it is complex code, describe the approach used to solve the issue.
> > If possible attach design doc, issue investigation, github discussion, etc.
> > * Testing:
> > * How is the code tested?
> > * Attach CD/CI run on the personal git repo.
> >
> > * PR examples:
> > * https://github.com/apache/ozone/pull/3980
> > * https://github.com/apache/ozone/pull/5265
> > * https://github.com/apache/ozone/pull/4701
> > * https://github.com/apache/ozone/pull/5283
> > * https://github.com/apache/ozone/pull/5300
> > * https://github.com/apache/ozone/pull/5301
> >
> > Thanks,
> > Hemant
> >
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ozone.apache.org
For additional commands, e-mail: dev-help@ozone.apache.org
Re: Ozone Jira and PR guidelines
Posted by Uma Maheswara Rao Gangumalla <um...@gmail.com>.
Thank you Hemant for starting the discussion on JIRA and PR descriptions.
Also reviewers should step up to check the JIRA/PR descriptions as well
without biased understanding of the JIRA.
We are doing JIRA scrub in community syncs and if we notice JIRAs without
descriptions we can close them right away.
Regards,
Uma
On Thu, Sep 21, 2023 at 9:55 AM Hemant Kumar <he...@apache.org> wrote:
> Hi Ozone Community,
> As we discussed in the last ozone community meeting about Ozone jiras and
> PRs not having enough information/details. Which makes it harder to
> understand when people outside the project look at them. Hence to make it
> better, I'm proposing the following guideline.
> Please take a look and let me know your thoughts. Once we are in agreement,
> I'll add them to Ozone onboarding wiki.
>
> *Jira description guideline:*
> * Title: Title should be a one liner stating the problem.
> * Description:
> * What is the problem? Is it a feature, improvement or bug? Add as
> many details as possible and related design doc and discussion.
> * For new features, add as many details as possible. If it is part of
> the big feature, attach parent jira.
> * For improvement, add the value it will bring. Is it an optimization,
> code simplification or something else?
> * For bugs, add steps to reproduce it. Where the root cause is unknown
> and needs investigation, it would be great to update the jira description
> or add the summary once the root cause is identified.
> * Jira examples:
> * https://issues.apache.org/jira/browse/HDDS-9272
> * https://issues.apache.org/jira/browse/HDDS-9322
> * https://issues.apache.org/jira/browse/HDDS-9291
> * https://issues.apache.org/jira/browse/HDDS-8940
> * https://issues.apache.org/jira/browse/HDDS-9282
>
> *PR description guideline:*
> * Title: Title should provide a one sentence overview of the purpose of the
> PR.
> * Description:
> * What changes are proposed in the PR? and Why?
> * Provide as much context and rationale for the pull request as
> possible. It could be copy-paste from the jira's description if the jira is
> well defined.
> * If it is complex code, describe the approach used to solve the issue.
> If possible attach design doc, issue investigation, github discussion, etc.
> * Testing:
> * How is the code tested?
> * Attach CD/CI run on the personal git repo.
>
> * PR examples:
> * https://github.com/apache/ozone/pull/3980
> * https://github.com/apache/ozone/pull/5265
> * https://github.com/apache/ozone/pull/4701
> * https://github.com/apache/ozone/pull/5283
> * https://github.com/apache/ozone/pull/5300
> * https://github.com/apache/ozone/pull/5301
>
> Thanks,
> Hemant
>
Re: Ozone Jira and PR guidelines
Posted by Siddharth Wagle <sw...@apache.org>.
Thanks, Hemant for kicking off this thread!
Jira and pull-requests hygiene are extremely important for posterity and
overall significantly improve collaboration with developers especially
cross timezones.
This should be added to the contributing guide:
https://github.com/apache/ozone/blob/master/CONTRIBUTING.md
Best,
Sid
On Thu, Sep 21, 2023 at 9:54 AM Hemant Kumar <he...@apache.org> wrote:
> Hi Ozone Community,
> As we discussed in the last ozone community meeting about Ozone jiras and
> PRs not having enough information/details. Which makes it harder to
> understand when people outside the project look at them. Hence to make it
> better, I'm proposing the following guideline.
> Please take a look and let me know your thoughts. Once we are in agreement,
> I'll add them to Ozone onboarding wiki.
>
> *Jira description guideline:*
> * Title: Title should be a one liner stating the problem.
> * Description:
> * What is the problem? Is it a feature, improvement or bug? Add as
> many details as possible and related design doc and discussion.
> * For new features, add as many details as possible. If it is part of
> the big feature, attach parent jira.
> * For improvement, add the value it will bring. Is it an optimization,
> code simplification or something else?
> * For bugs, add steps to reproduce it. Where the root cause is unknown
> and needs investigation, it would be great to update the jira description
> or add the summary once the root cause is identified.
> * Jira examples:
> * https://issues.apache.org/jira/browse/HDDS-9272
> * https://issues.apache.org/jira/browse/HDDS-9322
> * https://issues.apache.org/jira/browse/HDDS-9291
> * https://issues.apache.org/jira/browse/HDDS-8940
> * https://issues.apache.org/jira/browse/HDDS-9282
>
> *PR description guideline:*
> * Title: Title should provide a one sentence overview of the purpose of the
> PR.
> * Description:
> * What changes are proposed in the PR? and Why?
> * Provide as much context and rationale for the pull request as
> possible. It could be copy-paste from the jira's description if the jira is
> well defined.
> * If it is complex code, describe the approach used to solve the issue.
> If possible attach design doc, issue investigation, github discussion, etc.
> * Testing:
> * How is the code tested?
> * Attach CD/CI run on the personal git repo.
>
> * PR examples:
> * https://github.com/apache/ozone/pull/3980
> * https://github.com/apache/ozone/pull/5265
> * https://github.com/apache/ozone/pull/4701
> * https://github.com/apache/ozone/pull/5283
> * https://github.com/apache/ozone/pull/5300
> * https://github.com/apache/ozone/pull/5301
>
> Thanks,
> Hemant
>