You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@activemq.apache.org by Christopher Shannon <ch...@gmail.com> on 2022/03/24 20:25:33 UTC
[DISCUSS] Guidelines for new Jiras and Commit messages
As I brought up in the Artemis 2.21.0 vote thread I have noticed a pattern
of Jiras that have almost no information in them which makes it very
difficult to follow along with bug fixes and new features. This made
reviewing the current release more difficult. Some issues are trivial but
most issues should have a good description to document the change.
I am proposing that going forward we come up with a template/guide or
checklist of some sort for Jiras for people to follow, kind of like coding
standards or a checklist for reviewing pull requests.
It doesn't have to be super strict, but some guidelines might be nice. Off
the top of my head here are a few things:
New Features:
1) What's the motivation of the feature? Why is it needed?
2) A high level description on the plan to implement the feature
2) Maybe some details on how testing will be done
Bug Fixes:
1) How was the issue discovered?
2) How to reproduce and what versions are affected?
3) whats the proposed fix?
My main motivation here is Jiras but we could also have guidelines for
commit messages if we want too.
Thoughts?
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Justin Bertram <jb...@apache.org>.
Can you provide a few examples of problematic Jiras and/or commit messages?
Recently I started putting most (if not all) of the details for the change
in the commit message itself rather than in the Jira. These details are
added to the Jira implicitly as comments when the code is merged. However,
if the details are in the Jira only then when one is browsing the code it
is often required to open the related Jira to get the details for the
change.
Justin
On Thu, Mar 24, 2022 at 3:34 PM Christopher Shannon <
christopher.l.shannon@gmail.com> wrote:
> As I brought up in the Artemis 2.21.0 vote thread I have noticed a pattern
> of Jiras that have almost no information in them which makes it very
> difficult to follow along with bug fixes and new features. This made
> reviewing the current release more difficult. Some issues are trivial but
> most issues should have a good description to document the change.
>
> I am proposing that going forward we come up with a template/guide or
> checklist of some sort for Jiras for people to follow, kind of like coding
> standards or a checklist for reviewing pull requests.
>
> It doesn't have to be super strict, but some guidelines might be nice. Off
> the top of my head here are a few things:
>
> New Features:
> 1) What's the motivation of the feature? Why is it needed?
> 2) A high level description on the plan to implement the feature
> 2) Maybe some details on how testing will be done
>
> Bug Fixes:
> 1) How was the issue discovered?
> 2) How to reproduce and what versions are affected?
> 3) whats the proposed fix?
>
> My main motivation here is Jiras but we could also have guidelines for
> commit messages if we want too.
>
> Thoughts?
>
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Matt Pavlovich <ma...@gmail.com>.
Hi Chris-
Thanks for bringing this up.
> On Mar 25, 2022, at 5:43 AM, Christopher Shannon <ch...@gmail.com> wrote:
>
> Also, keep in mind not everyone is a developer. Many users are not going to
> want to dive into the code and are not familiar with Git or how to search
> Git history etc. Yeah it's not too hard with GitHub but it's still not as
> easy as searching Jira. Not everyone is running a Git bisect.
+1 I think this is really important for the community regarding the audience of JIRA notes vs Git commits.This project has had success over the years growing committers from admins, consultants and app developers-- it starts with the issue tracker.
I agree that it is important to document how an issue was discovered, in order to help other users to find it. Even with the “dreamt about it last night” scenario Clebert described — adding some humor to the notes doesn’t hurt anything =). Stacktrace and logs is always best.
I agree with @Robbie Gemmell that notes in the issue tracker (JIRA) is best and go with conscience commit messages.
To move this forward into practice— how about a JIRA ;-) ? We can flush out templates ideas there.
Thanks,
Matt Pavlovich
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Christopher Shannon <ch...@gmail.com>.
Having useful information in both is necessary of course but I still think
the place the most detail is Jira and having a more compact commit message
makes more sense. Git commits should be useful and describe the issue but
if you need to add a lot of detail then Jira is the place to put it.
Also, keep in mind not everyone is a developer. Many users are not going to
want to dive into the code and are not familiar with Git or how to search
Git history etc. Yeah it's not too hard with GitHub but it's still not as
easy as searching Jira. Not everyone is running a Git bisect.
Imagine a user who's an admin or someone else who just wants to use the
product and has a problem they think is a bug or something. They will
probably go look at Jira and see if something has been reported that
matches their problem (or search the forums or stackoverflow etc). If they
see 3 or 4 word descriptions in Jira it isn't like they are going to then
start searching Git history for a commit that solves their problem.
On Thu, Mar 24, 2022 at 9:23 PM Clebert Suconic <cl...@gmail.com>
wrote:
> I prefer having more information on the commit rather than the JIRA.
>
> When I’m referring to git blame it would help to have more information on
> the git commit than on the Jira BTW.
>
> I had many cases where I had to git bisect. Or find what was the change on
> the line.
>
> As you said it (cshanon) does not need to be verbose. But succinct messages
> would help.
>
>
>
> On Thu, Mar 24, 2022 at 6:51 PM Christopher Shannon <
> christopher.l.shannon@gmail.com> wrote:
>
> > Clebert, that is a fair point, mostly I was just giving examples off the
> > top of my head. How the issue was found may or may not be relevant
> > depending on the issue so it can be skipped. Really I just want there to
> be
> > something relevant that explains the issue in some detail and how much
> > detail depends on the complexity.
> >
> > Justin, for some examples you already gave them by describing what you've
> > been doing with putting stuff into the commit messages instead of Jira
> and
> > leaving the Jira description empty. Personally, I'm not a big fan of
> this
> > as I think the details should go into the Jira description so you see it
> > immediately when you load the Jira and the commit messages should be more
> > concise. While the commit comments get linked back to the Jira I still
> > think the details belong in the actual description and that is more
> > customary.
> >
> > But that's why I brought up a discussion thread to see what others
> thought.
> >
> > On Thu, Mar 24, 2022 at 6:11 PM Clebert Suconic <
> clebert.suconic@gmail.com
> > >
> > wrote:
> >
> > > Does it matter how an issue was found ?
> > >
> > > Some explanation in what the fix is that’s a fair point. But how it
> was
> > > found seems irrelevant to me.
> > >
> > >
> > > Like not trying to play sarcasm here but I once found an issue on my
> > > dreams. (Literally)
> > >
> > >
> > >
> > > On Thu, Mar 24, 2022 at 4:26 PM Christopher’ Shannon .
> > l.shannon@gmail.com>
> > > wrote:
> > >
> > > > As I brought up in othe Artemis 2.21.0 vote thread I xolahave
> noticed a
> > > > pattern
> > > > of Jiras that have almost no information in them which makes it very
> > > > difficult to follow along with bug fixes and new features. This made
> > > > reviewing the current release more difficult. Some issues are trivial
> > but
> > > > most issues should have a good description to document the change.
> > > >
> > > > I am proposing that going forward we come up with a template/guide or
> > > > checklist of some sort for Jiras for people to follow, kind of like
> > > coding
> > > > standards or a checklist for reviewing pull requests.
> > > >
> > > > It doesn't have to be super strict, but some guidelines might be
> nice.
> > > Off
> > > > the top of my head here are a few things:
> > > >
> > > > New Features:
> > > > 1) What's the motivation of the feature? Why is it needed?
> > > > 2) A high level description on the plan to implement the feature
> > > > 2) Maybe some details on how testing will be done
> > > >
> > > > Bug Fixes:
> > > > 1) How was the issue discovered?
> > > > 2) How to reproduce and what versions are affected?
> > > > 3) whats the proposed fix?
> > > >
> > > > My main motivation here is Jiras but we could also have guidelines
> for
> > > > commit messages if we want too.
> > > >
> > > > Thoughts?
> > > >
> > > --
> > > Clebert Suconic
> > >
> >
> --
> Clebert Suconic
>
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Clebert Suconic <cl...@gmail.com>.
I prefer having more information on the commit rather than the JIRA.
When I’m referring to git blame it would help to have more information on
the git commit than on the Jira BTW.
I had many cases where I had to git bisect. Or find what was the change on
the line.
As you said it (cshanon) does not need to be verbose. But succinct messages
would help.
On Thu, Mar 24, 2022 at 6:51 PM Christopher Shannon <
christopher.l.shannon@gmail.com> wrote:
> Clebert, that is a fair point, mostly I was just giving examples off the
> top of my head. How the issue was found may or may not be relevant
> depending on the issue so it can be skipped. Really I just want there to be
> something relevant that explains the issue in some detail and how much
> detail depends on the complexity.
>
> Justin, for some examples you already gave them by describing what you've
> been doing with putting stuff into the commit messages instead of Jira and
> leaving the Jira description empty. Personally, I'm not a big fan of this
> as I think the details should go into the Jira description so you see it
> immediately when you load the Jira and the commit messages should be more
> concise. While the commit comments get linked back to the Jira I still
> think the details belong in the actual description and that is more
> customary.
>
> But that's why I brought up a discussion thread to see what others thought.
>
> On Thu, Mar 24, 2022 at 6:11 PM Clebert Suconic <clebert.suconic@gmail.com
> >
> wrote:
>
> > Does it matter how an issue was found ?
> >
> > Some explanation in what the fix is that’s a fair point. But how it was
> > found seems irrelevant to me.
> >
> >
> > Like not trying to play sarcasm here but I once found an issue on my
> > dreams. (Literally)
> >
> >
> >
> > On Thu, Mar 24, 2022 at 4:26 PM Christopher’ Shannon .
> l.shannon@gmail.com>
> > wrote:
> >
> > > As I brought up in othe Artemis 2.21.0 vote thread I xolahave noticed a
> > > pattern
> > > of Jiras that have almost no information in them which makes it very
> > > difficult to follow along with bug fixes and new features. This made
> > > reviewing the current release more difficult. Some issues are trivial
> but
> > > most issues should have a good description to document the change.
> > >
> > > I am proposing that going forward we come up with a template/guide or
> > > checklist of some sort for Jiras for people to follow, kind of like
> > coding
> > > standards or a checklist for reviewing pull requests.
> > >
> > > It doesn't have to be super strict, but some guidelines might be nice.
> > Off
> > > the top of my head here are a few things:
> > >
> > > New Features:
> > > 1) What's the motivation of the feature? Why is it needed?
> > > 2) A high level description on the plan to implement the feature
> > > 2) Maybe some details on how testing will be done
> > >
> > > Bug Fixes:
> > > 1) How was the issue discovered?
> > > 2) How to reproduce and what versions are affected?
> > > 3) whats the proposed fix?
> > >
> > > My main motivation here is Jiras but we could also have guidelines for
> > > commit messages if we want too.
> > >
> > > Thoughts?
> > >
> > --
> > Clebert Suconic
> >
>
--
Clebert Suconic
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Étienne Hossack <ac...@hossack.me>.
+1 to this. Particularly if there's a desire to automate more of the announcements on the website.
If we wanted to go further someone could set up Jira fields and Github templates to enforce these.
It's good to have context in both commits and Jira, so worst case you copy your detailed commit message and either convert it to a user's perspective (instead of dev's) or expand on it.
For your proposed list the 1/How isn't required but can be helpful, the 2 and the 3 are for sure.
--
Étienne
On Thu, 24 Mar 2022, at 3:51 PM, Christopher Shannon wrote:
> Clebert, that is a fair point, mostly I was just giving examples off the
> top of my head. How the issue was found may or may not be relevant
> depending on the issue so it can be skipped. Really I just want there to be
> something relevant that explains the issue in some detail and how much
> detail depends on the complexity.
>
> Justin, for some examples you already gave them by describing what you've
> been doing with putting stuff into the commit messages instead of Jira and
> leaving the Jira description empty. Personally, I'm not a big fan of this
> as I think the details should go into the Jira description so you see it
> immediately when you load the Jira and the commit messages should be more
> concise. While the commit comments get linked back to the Jira I still
> think the details belong in the actual description and that is more
> customary.
>
> But that's why I brought up a discussion thread to see what others thought.
>
> On Thu, Mar 24, 2022 at 6:11 PM Clebert Suconic <cl...@gmail.com>
> wrote:
>
>> Does it matter how an issue was found ?
>>
>> Some explanation in what the fix is that’s a fair point. But how it was
>> found seems irrelevant to me.
>>
>>
>> Like not trying to play sarcasm here but I once found an issue on my
>> dreams. (Literally)
>>
>>
>>
>> On Thu, Mar 24, 2022 at 4:26 PM Christopher’ Shannon .l.shannon@gmail.com>
>> wrote:
>>
>> > As I brought up in othe Artemis 2.21.0 vote thread I xolahave noticed a
>> > pattern
>> > of Jiras that have almost no information in them which makes it very
>> > difficult to follow along with bug fixes and new features. This made
>> > reviewing the current release more difficult. Some issues are trivial but
>> > most issues should have a good description to document the change.
>> >
>> > I am proposing that going forward we come up with a template/guide or
>> > checklist of some sort for Jiras for people to follow, kind of like
>> coding
>> > standards or a checklist for reviewing pull requests.
>> >
>> > It doesn't have to be super strict, but some guidelines might be nice.
>> Off
>> > the top of my head here are a few things:
>> >
>> > New Features:
>> > 1) What's the motivation of the feature? Why is it needed?
>> > 2) A high level description on the plan to implement the feature
>> > 2) Maybe some details on how testing will be done
>> >
>> > Bug Fixes:
>> > 1) How was the issue discovered?
>> > 2) How to reproduce and what versions are affected?
>> > 3) whats the proposed fix?
>> >
>> > My main motivation here is Jiras but we could also have guidelines for
>> > commit messages if we want too.
>> >
>> > Thoughts?
>> >
>> --
>> Clebert Suconic
>>
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Christopher Shannon <ch...@gmail.com>.
Clebert, that is a fair point, mostly I was just giving examples off the
top of my head. How the issue was found may or may not be relevant
depending on the issue so it can be skipped. Really I just want there to be
something relevant that explains the issue in some detail and how much
detail depends on the complexity.
Justin, for some examples you already gave them by describing what you've
been doing with putting stuff into the commit messages instead of Jira and
leaving the Jira description empty. Personally, I'm not a big fan of this
as I think the details should go into the Jira description so you see it
immediately when you load the Jira and the commit messages should be more
concise. While the commit comments get linked back to the Jira I still
think the details belong in the actual description and that is more
customary.
But that's why I brought up a discussion thread to see what others thought.
On Thu, Mar 24, 2022 at 6:11 PM Clebert Suconic <cl...@gmail.com>
wrote:
> Does it matter how an issue was found ?
>
> Some explanation in what the fix is that’s a fair point. But how it was
> found seems irrelevant to me.
>
>
> Like not trying to play sarcasm here but I once found an issue on my
> dreams. (Literally)
>
>
>
> On Thu, Mar 24, 2022 at 4:26 PM Christopher’ Shannon .l.shannon@gmail.com>
> wrote:
>
> > As I brought up in othe Artemis 2.21.0 vote thread I xolahave noticed a
> > pattern
> > of Jiras that have almost no information in them which makes it very
> > difficult to follow along with bug fixes and new features. This made
> > reviewing the current release more difficult. Some issues are trivial but
> > most issues should have a good description to document the change.
> >
> > I am proposing that going forward we come up with a template/guide or
> > checklist of some sort for Jiras for people to follow, kind of like
> coding
> > standards or a checklist for reviewing pull requests.
> >
> > It doesn't have to be super strict, but some guidelines might be nice.
> Off
> > the top of my head here are a few things:
> >
> > New Features:
> > 1) What's the motivation of the feature? Why is it needed?
> > 2) A high level description on the plan to implement the feature
> > 2) Maybe some details on how testing will be done
> >
> > Bug Fixes:
> > 1) How was the issue discovered?
> > 2) How to reproduce and what versions are affected?
> > 3) whats the proposed fix?
> >
> > My main motivation here is Jiras but we could also have guidelines for
> > commit messages if we want too.
> >
> > Thoughts?
> >
> --
> Clebert Suconic
>
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Clebert Suconic <cl...@gmail.com>.
Does it matter how an issue was found ?
Some explanation in what the fix is that’s a fair point. But how it was
found seems irrelevant to me.
Like not trying to play sarcasm here but I once found an issue on my
dreams. (Literally)
On Thu, Mar 24, 2022 at 4:26 PM Christopher’ Shannon .l.shannon@gmail.com>
wrote:
> As I brought up in othe Artemis 2.21.0 vote thread I xolahave noticed a
> pattern
> of Jiras that have almost no information in them which makes it very
> difficult to follow along with bug fixes and new features. This made
> reviewing the current release more difficult. Some issues are trivial but
> most issues should have a good description to document the change.
>
> I am proposing that going forward we come up with a template/guide or
> checklist of some sort for Jiras for people to follow, kind of like coding
> standards or a checklist for reviewing pull requests.
>
> It doesn't have to be super strict, but some guidelines might be nice. Off
> the top of my head here are a few things:
>
> New Features:
> 1) What's the motivation of the feature? Why is it needed?
> 2) A high level description on the plan to implement the feature
> 2) Maybe some details on how testing will be done
>
> Bug Fixes:
> 1) How was the issue discovered?
> 2) How to reproduce and what versions are affected?
> 3) whats the proposed fix?
>
> My main motivation here is Jiras but we could also have guidelines for
> commit messages if we want too.
>
> Thoughts?
>
--
Clebert Suconic
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Robbie Gemmell <ro...@gmail.com>.
I similarly think many of the JIRAs dont have nearly enough detail. We
prepare release notes links/pages that link to JIRAs precisely because
they are meant for tracking issues, it really should have a good
summary of the issue for a user. Thats typically not really just the
same thing as a commit log a developer might be reading.
It is pretty common for users and developers to need to go back and
look at issues from years ago for many reasons, e.g because other
people hit them years later when using such old versions, or it
becomes clear later that the change caused another issue, or you are
looking at code you've either never seen or have forgotten and want to
understand how it came to be the way it is, etc etc. These can all
also be helped by JIRAs carrying useful expanded details. JIRAs can
also later help track things like relations in a ways that an old
commit cant.
I'm not a fan of gigantic commit messages thare are the only place
with all the details, people shouldnt need to read every commit log
for an issue to get a complete sense of why any change is being made
for example. Yes, commits should absolutely give appropriate info on
what each commit does, but they can typically be fairly succinct and
its often helpful if they are. An issue tracker on the hand is an
ideal place to elaborate on other non-critical info that perhaps could
still be useful to someone, and almost certainly better describe the
issue to a user rather than developer reading commits. Somewhat
similar, PRs e.g have useful developer discussions that can be good to
reference later but we typically dont then encode all those into the
commit log.
It can sometimes matter how an issue was found/hit. Maybe it points to
another more important problem, or an alternative or better fix. Maybe
how it was found was itself a misuse that can be rejected more simply.
Maybe it's just working as intended. I had to ask for some detail on a
completely empty JIRA recently, because from the title I thought there
was a decent chance it wasnt actually a bug at all, depending on how
in particular it was configured. Sure enough, once a description was
added I could say immediately that it wasnt a bug, it was behaving
exactly as the specification defined it for the configuration being
used; it was the expectations that were wrong, not the behaviour, and
having that detail made it obvious.
I also recall a JIRA some time ago that changed some bits, without
saying anything about why. The next release then contained a JIRA from
someone else that changed the same bits, without saying anything about
why; changing it back to what it was originally. Maybe if the JIRAs
had any detail, it would have never been changed.
On Thu, 24 Mar 2022 at 20:26, Christopher Shannon
<ch...@gmail.com> wrote:
>
> As I brought up in the Artemis 2.21.0 vote thread I have noticed a pattern
> of Jiras that have almost no information in them which makes it very
> difficult to follow along with bug fixes and new features. This made
> reviewing the current release more difficult. Some issues are trivial but
> most issues should have a good description to document the change.
>
> I am proposing that going forward we come up with a template/guide or
> checklist of some sort for Jiras for people to follow, kind of like coding
> standards or a checklist for reviewing pull requests.
>
> It doesn't have to be super strict, but some guidelines might be nice. Off
> the top of my head here are a few things:
>
> New Features:
> 1) What's the motivation of the feature? Why is it needed?
> 2) A high level description on the plan to implement the feature
> 2) Maybe some details on how testing will be done
>
> Bug Fixes:
> 1) How was the issue discovered?
> 2) How to reproduce and what versions are affected?
> 3) whats the proposed fix?
>
> My main motivation here is Jiras but we could also have guidelines for
> commit messages if we want too.
>
> Thoughts?
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Christopher Shannon <ch...@gmail.com>.
Here are a few examples of Jiras I did. Obviously I'm not perfect but I
just wanted to show samples of what I think are decent descriptions and
what I'm talkin about when I'm asking for people to include more
information:
https://issues.apache.org/jira/browse/AMQ-8287
https://issues.apache.org/jira/browse/AMQ-8183
https://issues.apache.org/jira/browse/AMQ-8509
https://issues.apache.org/jira/browse/ARTEMIS-2802
https://issues.apache.org/jira/browse/ARTEMIS-2613
https://issues.apache.org/jira/browse/ARTEMIS-2565
On Thu, Mar 24, 2022 at 4:25 PM Christopher Shannon <
christopher.l.shannon@gmail.com> wrote:
> As I brought up in the Artemis 2.21.0 vote thread I have noticed a pattern
> of Jiras that have almost no information in them which makes it very
> difficult to follow along with bug fixes and new features. This made
> reviewing the current release more difficult. Some issues are trivial but
> most issues should have a good description to document the change.
>
> I am proposing that going forward we come up with a template/guide or
> checklist of some sort for Jiras for people to follow, kind of like coding
> standards or a checklist for reviewing pull requests.
>
> It doesn't have to be super strict, but some guidelines might be nice. Off
> the top of my head here are a few things:
>
> New Features:
> 1) What's the motivation of the feature? Why is it needed?
> 2) A high level description on the plan to implement the feature
> 2) Maybe some details on how testing will be done
>
> Bug Fixes:
> 1) How was the issue discovered?
> 2) How to reproduce and what versions are affected?
> 3) whats the proposed fix?
>
> My main motivation here is Jiras but we could also have guidelines for
> commit messages if we want too.
>
> Thoughts?
>
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Christopher Shannon <ch...@gmail.com>.
As I said in my original post I don't think we need to be super strict and
probably don't need to enforce anything (at least not yet). When I started
the thread to establish guidelines I meant that...they would just be
guidelines or a checklist that can be loosely followed as a template for
people to help them out with filling out new Jiras. There's going to be
reasons to deviate but it could be a good starting point.
My goal here is not to create a bunch of work on people or for it to be a
big burden, just to help make sure Jiras have useful info. So maybe at
first we just add a section to the committer page that just describes the
kind of information a good Jira and good commit message should contain and
go from there vs establishing anything formal or enforced.
On Sat, Mar 26, 2022 at 11:20 AM Clebert Suconic <cl...@gmail.com>
wrote:
> Is this a matter of just be careful and provide the information with
> the format we have now... or we want to enforce and change to a
> certain format within commit messages (like Netty does for instance)?
>
> On Sat, Mar 26, 2022 at 8:28 AM Christopher Shannon
> <ch...@gmail.com> wrote:
> >
> > JB,
> >
> > Right, simple things don’t need much detail. It’s pretty easy to just use
> > some common sense and to tell when something is trivial and doesn’t need
> a
> > lot of detail vs a more complex issue that should have a lot more
> written.
> > Things like fixing a NPE, dependency updates, logging changes, etc don’t
> > need much info at all and could just have a title and no description of
> the
> > title is self explanatory.
> >
> > But new features, most bug fixes, or major changes should have some
> details
> > written to help understand the issue.
> >
> > On Sat, Mar 26, 2022 at 1:40 AM Jean-Baptiste Onofré <jb...@nanthrax.net>
> > wrote:
> >
> > > If we distinguish the simple jira where the title is enough (I'm
> > > thinking about the dependency updates where the title is enough, but
> > > these Jiras are good for the tracking), I generally agree.
> > >
> > > +1 to have some guidelines in the contributor guide (in source repo
> > > and/or website) and also in PR template on github.
> > >
> > > Regards
> > > JB
> > >
> > > On Thu, Mar 24, 2022 at 9:25 PM Christopher Shannon
> > > <ch...@gmail.com> wrote:
> > > >
> > > > As I brought up in the Artemis 2.21.0 vote thread I have noticed a
> > > pattern
> > > > of Jiras that have almost no information in them which makes it very
> > > > difficult to follow along with bug fixes and new features. This made
> > > > reviewing the current release more difficult. Some issues are
> trivial but
> > > > most issues should have a good description to document the change.
> > > >
> > > > I am proposing that going forward we come up with a template/guide or
> > > > checklist of some sort for Jiras for people to follow, kind of like
> > > coding
> > > > standards or a checklist for reviewing pull requests.
> > > >
> > > > It doesn't have to be super strict, but some guidelines might be
> nice.
> > > Off
> > > > the top of my head here are a few things:
> > > >
> > > > New Features:
> > > > 1) What's the motivation of the feature? Why is it needed?
> > > > 2) A high level description on the plan to implement the feature
> > > > 2) Maybe some details on how testing will be done
> > > >
> > > > Bug Fixes:
> > > > 1) How was the issue discovered?
> > > > 2) How to reproduce and what versions are affected?
> > > > 3) whats the proposed fix?
> > > >
> > > > My main motivation here is Jiras but we could also have guidelines
> for
> > > > commit messages if we want too.
> > > >
> > > > Thoughts?
> > >
>
>
>
> --
> Clebert Suconic
>
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Clebert Suconic <cl...@gmail.com>.
Is this a matter of just be careful and provide the information with
the format we have now... or we want to enforce and change to a
certain format within commit messages (like Netty does for instance)?
On Sat, Mar 26, 2022 at 8:28 AM Christopher Shannon
<ch...@gmail.com> wrote:
>
> JB,
>
> Right, simple things don’t need much detail. It’s pretty easy to just use
> some common sense and to tell when something is trivial and doesn’t need a
> lot of detail vs a more complex issue that should have a lot more written.
> Things like fixing a NPE, dependency updates, logging changes, etc don’t
> need much info at all and could just have a title and no description of the
> title is self explanatory.
>
> But new features, most bug fixes, or major changes should have some details
> written to help understand the issue.
>
> On Sat, Mar 26, 2022 at 1:40 AM Jean-Baptiste Onofré <jb...@nanthrax.net>
> wrote:
>
> > If we distinguish the simple jira where the title is enough (I'm
> > thinking about the dependency updates where the title is enough, but
> > these Jiras are good for the tracking), I generally agree.
> >
> > +1 to have some guidelines in the contributor guide (in source repo
> > and/or website) and also in PR template on github.
> >
> > Regards
> > JB
> >
> > On Thu, Mar 24, 2022 at 9:25 PM Christopher Shannon
> > <ch...@gmail.com> wrote:
> > >
> > > As I brought up in the Artemis 2.21.0 vote thread I have noticed a
> > pattern
> > > of Jiras that have almost no information in them which makes it very
> > > difficult to follow along with bug fixes and new features. This made
> > > reviewing the current release more difficult. Some issues are trivial but
> > > most issues should have a good description to document the change.
> > >
> > > I am proposing that going forward we come up with a template/guide or
> > > checklist of some sort for Jiras for people to follow, kind of like
> > coding
> > > standards or a checklist for reviewing pull requests.
> > >
> > > It doesn't have to be super strict, but some guidelines might be nice.
> > Off
> > > the top of my head here are a few things:
> > >
> > > New Features:
> > > 1) What's the motivation of the feature? Why is it needed?
> > > 2) A high level description on the plan to implement the feature
> > > 2) Maybe some details on how testing will be done
> > >
> > > Bug Fixes:
> > > 1) How was the issue discovered?
> > > 2) How to reproduce and what versions are affected?
> > > 3) whats the proposed fix?
> > >
> > > My main motivation here is Jiras but we could also have guidelines for
> > > commit messages if we want too.
> > >
> > > Thoughts?
> >
--
Clebert Suconic
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Christopher Shannon <ch...@gmail.com>.
JB,
Right, simple things don’t need much detail. It’s pretty easy to just use
some common sense and to tell when something is trivial and doesn’t need a
lot of detail vs a more complex issue that should have a lot more written.
Things like fixing a NPE, dependency updates, logging changes, etc don’t
need much info at all and could just have a title and no description of the
title is self explanatory.
But new features, most bug fixes, or major changes should have some details
written to help understand the issue.
On Sat, Mar 26, 2022 at 1:40 AM Jean-Baptiste Onofré <jb...@nanthrax.net>
wrote:
> If we distinguish the simple jira where the title is enough (I'm
> thinking about the dependency updates where the title is enough, but
> these Jiras are good for the tracking), I generally agree.
>
> +1 to have some guidelines in the contributor guide (in source repo
> and/or website) and also in PR template on github.
>
> Regards
> JB
>
> On Thu, Mar 24, 2022 at 9:25 PM Christopher Shannon
> <ch...@gmail.com> wrote:
> >
> > As I brought up in the Artemis 2.21.0 vote thread I have noticed a
> pattern
> > of Jiras that have almost no information in them which makes it very
> > difficult to follow along with bug fixes and new features. This made
> > reviewing the current release more difficult. Some issues are trivial but
> > most issues should have a good description to document the change.
> >
> > I am proposing that going forward we come up with a template/guide or
> > checklist of some sort for Jiras for people to follow, kind of like
> coding
> > standards or a checklist for reviewing pull requests.
> >
> > It doesn't have to be super strict, but some guidelines might be nice.
> Off
> > the top of my head here are a few things:
> >
> > New Features:
> > 1) What's the motivation of the feature? Why is it needed?
> > 2) A high level description on the plan to implement the feature
> > 2) Maybe some details on how testing will be done
> >
> > Bug Fixes:
> > 1) How was the issue discovered?
> > 2) How to reproduce and what versions are affected?
> > 3) whats the proposed fix?
> >
> > My main motivation here is Jiras but we could also have guidelines for
> > commit messages if we want too.
> >
> > Thoughts?
>
Re: [DISCUSS] Guidelines for new Jiras and Commit messages
Posted by Jean-Baptiste Onofré <jb...@nanthrax.net>.
If we distinguish the simple jira where the title is enough (I'm
thinking about the dependency updates where the title is enough, but
these Jiras are good for the tracking), I generally agree.
+1 to have some guidelines in the contributor guide (in source repo
and/or website) and also in PR template on github.
Regards
JB
On Thu, Mar 24, 2022 at 9:25 PM Christopher Shannon
<ch...@gmail.com> wrote:
>
> As I brought up in the Artemis 2.21.0 vote thread I have noticed a pattern
> of Jiras that have almost no information in them which makes it very
> difficult to follow along with bug fixes and new features. This made
> reviewing the current release more difficult. Some issues are trivial but
> most issues should have a good description to document the change.
>
> I am proposing that going forward we come up with a template/guide or
> checklist of some sort for Jiras for people to follow, kind of like coding
> standards or a checklist for reviewing pull requests.
>
> It doesn't have to be super strict, but some guidelines might be nice. Off
> the top of my head here are a few things:
>
> New Features:
> 1) What's the motivation of the feature? Why is it needed?
> 2) A high level description on the plan to implement the feature
> 2) Maybe some details on how testing will be done
>
> Bug Fixes:
> 1) How was the issue discovered?
> 2) How to reproduce and what versions are affected?
> 3) whats the proposed fix?
>
> My main motivation here is Jiras but we could also have guidelines for
> commit messages if we want too.
>
> Thoughts?