On 2019-09-13 15:10:42 +0000 (+0000), Khalil, Ghada wrote: [...] https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines [...]
I personally don't see a big barrier to creating a generic storyboard for spelling or cleanup tasks. Happy to hear from others their opinion. I'm not terribly concerned about a few small updates without a link, but we should all aim to favor traceability (and document the purpose for the changes we're making). [...]
This topic comes up with some frequency in a variety of free/libre open-source projects to which I contribute, and from what I've seen every bit of bureaucracy you add around submitting a contribution is that much less fun the process becomes for people. Some amount of red tape and process overhead is unfortunately always going to be necessary, but I find it helps to make compromises to reduce that complexity wherever and whenever you possibly can. Not that I have a horse in this race, but I find it's hard to overstate the value of a well-written commit message, and it can be worth 10x more than a link to a disorganized pile of notes in a defect tracker. I realize a lot of developers don't take the time to provide thorough exposition in their commit messages, but this is something for which I consistently review. The commit message should tell me everything I need to know about a change without needing to follow links to defect reports or mailing list posts. Links to external references can be useful citations to help paint the bigger picture and provide background on decisions which were made, but if the commit message is sufficiently explanatory then it saves time both for people reviewing the proposed change *and* for folks looking back through the commit history years down the line. What if some unfortunate disaster befalls the materials linked from the commit message? Or what if I'm on a plane/train/boat with a clone of the Git repository but no viable access to the Internet? Linking to additional information is certainly a good thing to do when it's available, but it's no substitute for clearly describing in a commit message why that change was needed. And if the commit message already tells people everything they need to know about the change, why bother making extra work for developers by requiring them to file a defect (which in many cases may only be a considered a "defect" through a significant stretch of imagination) in a separate system only to immediately mark it as done? The wiki article you linked gives these two reasons: The story/bug will give reviewers context for the code changes. This will also be used to help determine the relative priority of the code changes. If the commit is written at the same time the defect is reported, what additional context can the report really provide if the same information is included in the commit message already? As for prioritization, what if it's not a high-priority change to begin with? What difference does filing a defect reference for it make in that case? Perhaps if a developer feels their change should be a higher review priority, then a corresponding tracked task is warranted; but if they don't create one they are basically saying, "here's a patch, review it when you have time, it's not urgent." One other reason that wiki page doesn't mention but can be important is if the change fixes a bug in the software which a user is likely to notice in an earlier release and may consider filing a defect report about themselves, since it can save them some time when they go to file it and find there's already one there marked fixed in a later release. This can of course be addressed by having reviewers recommend and developers be diligent about incorporating clear release notes for fixes which fit these criteria, since those users are similarly likely to check release notes first, but depending on the situation reviewers could still be well within reason to request (or create, since this is a collaboration, right?) a corresponding defect report to go with the change. Anyway, sorry for the lengthy soapbox speech. It doesn't really impact me either way as a mostly outside observer, but I do think that it's in the best interests of community health to try and keep the process of collaborating as enjoyable as possible. Having strict rules that even the tiniest change also requires task tracking erodes that enjoyment, and degrades the overall contributor experience. It's something to keep in mind. -- Jeremy Stanley