Hi, Let me start by saying that this discussion is more about guidelines rather than rules which can make the job of certain people easier so such discussions are important.
Personally, I prefer having the problem/symptoms in the summary of the JIRA/commit. If the root cause fits (does not make the summary overly long) then I might put it as well. >From my perspective this makes the life of end users, reviewers, and newcomers to a project easier. Let's consider for example the role of support engineers. This group of people are using JIRA very often (maybe even more than developers) and usually have to deal with a stack consisting of many separate projects. When the customer reports a problem it's not easy to dive directly into the code even if they know exactly which project is to blame. Usually the first thing to do is search the JIRA for cases reporting similar problems/symptoms. For reviewers, it is important to understand what is the problem that we're trying to fix and if that is not in the Jira their job becomes much more difficult. When people put too much emphasis on the root cause or the solution then it's hard to understand why the change is needed in the first place. I've seen a lot of bug reports where people submit a PR (it might or might not have a test) without really saying what the problem is. I don't mind if this happens since as other people mentioned not everyone works/thinks the same way but I will ask clarifications till I understand what the problem is otherwise it's hard for me to review a part that potentially I don't know much about. For people new to the project, I would argue that it's much easier to understand a case if it describes a problem/symptoms rather than the root cause/solution. This is just from my personal experience when I dive into new projects. Sometimes people start a JIRA/PR without much context by proposing changes to some classes and I cannot possibly follow the discussion unless I written those classes myself. On the other hand everybody can understand expressions like "wrong results", "invalid plan", "missing filter", "memory leak", "Exception when ...". So far we really focused into bug reports but what's also important for the summary to convey is the nature of the change (bug vs feature vs refactoring vs perf improvements, etc.). This can be done if the words are chosen correctly. Best, Stamatis On Fri, Jan 14, 2022, 11:30 PM Jacques Nadeau <jacq...@apache.org> wrote: > > > > Under the current process, the Jira subject becomes the commit message > > > I didn't know this was perceived as a "rule" and I don't follow it (oops?). > I also don't agree with it being a good idea. I typically put substantially > more information in a commit message than a jira subject. A commit message > also comes after resolution whereas a jira subject comes before resolution. > I don't generally think it is a good idea to change a jira subject on > commit as I find it confusing when you're actually tracking a jira. If I > were to change the subject on commit, I would be inclined to change it to > what I changed, not a symptom. > > > > As a reviewer, am I within my rights to say ‘I’m not going to even read > > your code until you tell me what problem you are trying to solve?’. > > > If a commit message doesn't clearly state the purpose of the patch, I'd be > completely comfortable asking the user to update the commit message to > clarify the purpose of the patch. I definitely wouldn't say it like that > quote does. > > > > Given that we have far more contributions than active reviews, and that I > > am one of the most prolific reviewers, I suspect that I am. > > > I don't think this is a constructive statement. It presents an argument > (likely accidental) that because you do more of this kind of work, your > opinion matters more than others'. I don't agree with this sentiment. If > anything, I think we should be doing things to increase others' > contributions--potentially at the cost of some small fraction of yours. > Having a bus factor of one is a disservice to the community. Don't take > this as a lack of appreciation and awe of your amazing contributions, just > an expression of discomfort around what effectively feels like "pulling > rank". > > what about reviewers and end users? > > > I agree that these stakeholders are important. That being said, I haven't > heard a lot of end users' complaints about our jira subjects or commit > messages. Did I miss this? >
