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 <christopher.l.shan...@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?
