[Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks: I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags. There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does. Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes. I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose. Thoughts? Sau!
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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. 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). Regards, Ghada -----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages StarlingX Folks: I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags. There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does. Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes. I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose. Thoughts? Sau! _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
+2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
-1. Commit messages are update reasons and just as traceable. Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"? bruej -----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 8:30 AM To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages +2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
I would argue that is very bad example, why would a single project all of sudden wants to switch to Python3? Is this part of release goal to start using Python 3? Is this priority for the release? Small change need more context so code reviewers know why such a change is proposed. Dariush -----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: September-13-19 11:37 AM To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages -1. Commit messages are update reasons and just as traceable. Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"? bruej -----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 8:30 AM To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages +2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
It's just an example, Dariush, of an internal change that would not impact an end user. Insert your own example if needed. :) Commit messages can provide plenty of context. If they are written well, of course, which the reviewers can verify / enforce. I'm not opposed to using SB and LP to document changes. But I don't think it's necessary to mandate it for every single change. brucej -----Original Message----- From: Eslimi, Dariush [mailto:Dariush.Eslimi@windriver.com] Sent: Friday, September 13, 2019 8:53 AM To: Jones, Bruce E <bruce.e.jones@intel.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages I would argue that is very bad example, why would a single project all of sudden wants to switch to Python3? Is this part of release goal to start using Python 3? Is this priority for the release? Small change need more context so code reviewers know why such a change is proposed. Dariush -----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: September-13-19 11:37 AM To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages -1. Commit messages are update reasons and just as traceable. Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"? bruej -----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 8:30 AM To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages +2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
There seem to be a lot of small changes that are being posted without quality or traceable reasoning and I feel that creating a SB and tasks for like changes helps reviewers and project/content managers.
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: Friday, September 13, 2019 12:54 PM To: Eslimi, Dariush; MacDonald, Eric; Khalil, Ghada; Saul Wold; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages Importance: High
It's just an example, Dariush, of an internal change that would not impact an end user. Insert your own example if needed. :)
Commit messages can provide plenty of context. If they are written well, of course, which the reviewers can verify / enforce.
I'm not opposed to using SB and LP to document changes. But I don't think it's necessary to mandate it for every single change.
brucej
-----Original Message----- From: Eslimi, Dariush [mailto:Dariush.Eslimi@windriver.com] Sent: Friday, September 13, 2019 8:53 AM To: Jones, Bruce E <bruce.e.jones@intel.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages
I would argue that is very bad example, why would a single project all of sudden wants to switch to Python3? Is this part of release goal to start using Python 3? Is this priority for the release?
Small change need more context so code reviewers know why such a change is proposed.
Dariush
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: September-13-19 11:37 AM To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
-1. Commit messages are update reasons and just as traceable.
Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"?
bruej
-----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 8:30 AM To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
+2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
A good point, Eric. As a reviewer, I think it would be fair to say "I don't understand this change, can you please elaborate in the commit message or in a Story?". But if the change is well understood by the reviewers (because it has a clear commit message), why ask the developer to do more work than needed? brucej -----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 10:28 AM To: Jones, Bruce E <bruce.e.jones@intel.com>; Eslimi, Dariush <Dariush.Eslimi@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages There seem to be a lot of small changes that are being posted without quality or traceable reasoning and I feel that creating a SB and tasks for like changes helps reviewers and project/content managers.
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: Friday, September 13, 2019 12:54 PM To: Eslimi, Dariush; MacDonald, Eric; Khalil, Ghada; Saul Wold; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages Importance: High
It's just an example, Dariush, of an internal change that would not impact an end user. Insert your own example if needed. :)
Commit messages can provide plenty of context. If they are written well, of course, which the reviewers can verify / enforce.
I'm not opposed to using SB and LP to document changes. But I don't think it's necessary to mandate it for every single change.
brucej
-----Original Message----- From: Eslimi, Dariush [mailto:Dariush.Eslimi@windriver.com] Sent: Friday, September 13, 2019 8:53 AM To: Jones, Bruce E <bruce.e.jones@intel.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages
I would argue that is very bad example, why would a single project all of sudden wants to switch to Python3? Is this part of release goal to start using Python 3? Is this priority for the release?
Small change need more context so code reviewers know why such a change is proposed.
Dariush
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: September-13-19 11:37 AM To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
-1. Commit messages are update reasons and just as traceable.
Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"?
bruej
-----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 8:30 AM To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
+2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
On 9/13/19 10:27 AM, MacDonald, Eric wrote:
There seem to be a lot of small changes that are being posted without quality or traceable reasoning and I feel that creating a SB and tasks for like changes helps reviewers and project/content managers.
The group of recent changes have been talked about before as part of the over all improvements in order to address various aspects of working with openSUSE and warning that are generated from that build. These are mostly small changes as you point out and are understandable. Sau!
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: Friday, September 13, 2019 12:54 PM To: Eslimi, Dariush; MacDonald, Eric; Khalil, Ghada; Saul Wold; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages Importance: High
It's just an example, Dariush, of an internal change that would not impact an end user. Insert your own example if needed. :)
Commit messages can provide plenty of context. If they are written well, of course, which the reviewers can verify / enforce.
I'm not opposed to using SB and LP to document changes. But I don't think it's necessary to mandate it for every single change.
brucej
-----Original Message----- From: Eslimi, Dariush [mailto:Dariush.Eslimi@windriver.com] Sent: Friday, September 13, 2019 8:53 AM To: Jones, Bruce E <bruce.e.jones@intel.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages
I would argue that is very bad example, why would a single project all of sudden wants to switch to Python3? Is this part of release goal to start using Python 3? Is this priority for the release?
Small change need more context so code reviewers know why such a change is proposed.
Dariush
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: September-13-19 11:37 AM To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
-1. Commit messages are update reasons and just as traceable.
Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"?
bruej
-----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 8:30 AM To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
+2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
There are stories created for other similar cleanup or like activities; why not for changes in support of opensuse (this example)? https://storyboard.openstack.org/#!/story/2006508 - Move specfiles from OBS to Gerri https://storyboard.openstack.org/#!/story/2006425 - Code cleanup in fault component Inconsistency breads complacency ... Eric.
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Friday, September 13, 2019 2:08 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
On 9/13/19 10:27 AM, MacDonald, Eric wrote:
There seem to be a lot of small changes that are being posted without quality or traceable reasoning and I feel that creating a SB and tasks for like changes helps reviewers and project/content managers.
The group of recent changes have been talked about before as part of the over all improvements in order to address various aspects of working with openSUSE and warning that are generated from that build.
These are mostly small changes as you point out and are understandable.
Sau!
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: Friday, September 13, 2019 12:54 PM To: Eslimi, Dariush; MacDonald, Eric; Khalil, Ghada; Saul Wold; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages Importance: High
It's just an example, Dariush, of an internal change that would not impact an end user. Insert your own example if needed. :)
Commit messages can provide plenty of context. If they are written well, of course, which the reviewers can verify / enforce.
I'm not opposed to using SB and LP to document changes. But I don't think it's necessary to mandate it for every single change.
brucej
-----Original Message----- From: Eslimi, Dariush [mailto:Dariush.Eslimi@windriver.com] Sent: Friday, September 13, 2019 8:53 AM To: Jones, Bruce E <bruce.e.jones@intel.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages
I would argue that is very bad example, why would a single project all of sudden wants to switch to Python3? Is this part of release goal to start using Python 3? Is this priority for the release?
Small change need more context so code reviewers know why such a change is proposed.
Dariush
-----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: September-13-19 11:37 AM To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
-1. Commit messages are update reasons and just as traceable.
Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"?
bruej
-----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 8:30 AM To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
+2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
On 9/13/19, 1:31 PM, "MacDonald, Eric" <Eric.MacDonald@windriver.com> wrote: There are stories created for other similar cleanup or like activities; why not for changes in support of opensuse (this example)? https://storyboard.openstack.org/#!/story/2006508 - Move specfiles from OBS to Gerri https://storyboard.openstack.org/#!/story/2006425 - Code cleanup in fault component As a contributor now I know that if I don't create these stories, a reviewer will complain about not having it even if the commit message is enough clear. I you open the stories you'll see that doesn't add any value more than the provided commit message. I create those above, but I've seen others with the same format. The Goodhart's law[0] states that "When a measure becomes a target, it ceases to be a good measure.". If our goal is to have stories and bugs in all contributions we'll end having meaningless stories/bugs. [0] https://en.wikipedia.org/wiki/Goodhart%27s_law Inconsistency breads complacency ... Eric. > -----Original Message----- > From: Saul Wold [mailto:sgw@linux.intel.com] > Sent: Friday, September 13, 2019 2:08 PM > To: starlingx-discuss@lists.starlingx.io > Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages > > > > On 9/13/19 10:27 AM, MacDonald, Eric wrote: > > There seem to be a lot of small changes that are being posted without quality or traceable reasoning > and I feel that creating a SB and tasks for like changes helps reviewers and project/content managers. > > > The group of recent changes have been talked about before as part of the > over all improvements in order to address various aspects of working > with openSUSE and warning that are generated from that build. > > These are mostly small changes as you point out and are understandable. > > Sau! > > >> -----Original Message----- > >> From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] > >> Sent: Friday, September 13, 2019 12:54 PM > >> To: Eslimi, Dariush; MacDonald, Eric; Khalil, Ghada; Saul Wold; starlingx-discuss@lists.starlingx.io > >> Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages > >> Importance: High > >> > >> It's just an example, Dariush, of an internal change that would not impact an end user. Insert your > own > >> example if needed. :) > >> > >> Commit messages can provide plenty of context. If they are written well, of course, which the > reviewers > >> can verify / enforce. > >> > >> I'm not opposed to using SB and LP to document changes. But I don't think it's necessary to mandate > it > >> for every single change. > >> > >> brucej > >> > >> > >> -----Original Message----- > >> From: Eslimi, Dariush [mailto:Dariush.Eslimi@windriver.com] > >> Sent: Friday, September 13, 2019 8:53 AM > >> To: Jones, Bruce E <bruce.e.jones@intel.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; > >> Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- > >> discuss@lists.starlingx.io > >> Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages > >> > >> I would argue that is very bad example, why would a single project all of sudden wants to switch to > >> Python3? > >> Is this part of release goal to start using Python 3? Is this priority for the release? > >> > >> Small change need more context so code reviewers know why such a change is proposed. > >> > >> Dariush > >> > >> -----Original Message----- > >> From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] > >> Sent: September-13-19 11:37 AM > >> To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada > <Ghada.Khalil@windriver.com>; > >> Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io > >> Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages > >> > >> -1. Commit messages are update reasons and just as traceable. > >> > >> Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"? > >> > >> bruej > >> > >> -----Original Message----- > >> From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] > >> Sent: Friday, September 13, 2019 8:30 AM > >> To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- > >> discuss@lists.starlingx.io > >> Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages > >> > >> +2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to. > >> > >>> -----Original Message----- > >>> From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] > >>> Sent: Friday, September 13, 2019 11:11 AM > >>> To: Saul Wold; starlingx-discuss@lists.starlingx.io > >>> Subject: Re: [Starlingx-discuss] Please Review: Requirements for > >>> commit messages > >>> > >>> Hi Saul, > >>> This was discussed previously and, as a community, we agreed that this > >>> is the guideline for starlingx submissions > >>> > >>> From > >>> https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines > >>> Link your review to a StoryBoard Story or Launchpad Bug For > >>> traceability, always link your code change to a story or bug. 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. > >>> > >>> > >>> 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). > >>> > >>> Regards, > >>> Ghada > >>> > >>> -----Original Message----- > >>> From: Saul Wold [mailto:sgw@linux.intel.com] > >>> Sent: Thursday, September 12, 2019 5:53 PM > >>> To: starlingx-discuss@lists.starlingx.io > >>> Subject: [Starlingx-discuss] Please Review: Requirements for commit > >>> messages > >>> > >>> > >>> StarlingX Folks: > >>> > >>> I would like to clarify the requirement or lack there of for having Bugs or Stories in commit > messages. > >>> There are patches that are clearly addressing bug fixes and those > >>> should have a Closes-Bug; there are commits that are clearly implementing features that should > have > >> the Story/Task tags. > >>> > >>> There are also commits that fall in between, they are not directly > >>> related to a given feature or have a bug filed, they are typically > >>> smaller and are fairly self-documenting or have good commit messages explaining why the change > is > >> needed, not just what the change does. > >>> > >>> Ultimately Closes-Bugs and Story tags will help reviewers and other > >>> get the infomration needed to create release notes, but we don't need > >>> to document every change like spelling, indentation, fixing compiler warnings in Release notes. > >>> > >>> I believe that we should have some flexibility in allowing for changes > >>> without related launchpad or story connections. This can help reduce > >>> the barrier to entry for small changes that community members may want to propose. > >>> > >>> Thoughts? > >>> > >>> Sau! > >>> > >>> _______________________________________________ > >>> Starlingx-discuss mailing list > >>> Starlingx-discuss@lists.starlingx.io > >>> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > >>> _______________________________________________ > >>> Starlingx-discuss mailing list > >>> Starlingx-discuss@lists.starlingx.io > >>> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > >> _______________________________________________ > >> Starlingx-discuss mailing list > >> Starlingx-discuss@lists.starlingx.io > >> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > >> _______________________________________________ > >> Starlingx-discuss mailing list > >> Starlingx-discuss@lists.starlingx.io > >> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > > _______________________________________________ > > Starlingx-discuss mailing list > > Starlingx-discuss@lists.starlingx.io > > http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > > > > _______________________________________________ > Starlingx-discuss mailing list > Starlingx-discuss@lists.starlingx.io > http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
... but the Story itself relates all the updates regardless of the wording content and I see value in that.
-----Original Message----- From: Cordoba Malibran, Erich [mailto:erich.cordoba.malibran@intel.com] Sent: Friday, September 13, 2019 3:27 PM To: MacDonald, Eric; Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages Importance: High
On 9/13/19, 1:31 PM, "MacDonald, Eric" <Eric.MacDonald@windriver.com> wrote:
There are stories created for other similar cleanup or like activities; why not for changes in support of opensuse (this example)?
https://storyboard.openstack.org/#!/story/2006508 - Move specfiles from OBS to Gerri https://storyboard.openstack.org/#!/story/2006425 - Code cleanup in fault component
As a contributor now I know that if I don't create these stories, a reviewer will complain about not having it even if the commit message is enough clear. I you open the stories you'll see that doesn't add any value more than the provided commit message. I create those above, but I've seen others with the same format.
The Goodhart's law[0] states that "When a measure becomes a target, it ceases to be a good measure.". If our goal is to have stories and bugs in all contributions we'll end having meaningless stories/bugs.
[0] https://en.wikipedia.org/wiki/Goodhart%27s_law
Inconsistency breads complacency ...
Eric.
> -----Original Message----- > From: Saul Wold [mailto:sgw@linux.intel.com] > Sent: Friday, September 13, 2019 2:08 PM > To: starlingx-discuss@lists.starlingx.io > Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages > > > > On 9/13/19 10:27 AM, MacDonald, Eric wrote: > > There seem to be a lot of small changes that are being posted without quality or traceable reasoning > and I feel that creating a SB and tasks for like changes helps reviewers and project/content managers. > > > The group of recent changes have been talked about before as part of the > over all improvements in order to address various aspects of working > with openSUSE and warning that are generated from that build. > > These are mostly small changes as you point out and are understandable. > > Sau! > > >> -----Original Message----- > >> From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] > >> Sent: Friday, September 13, 2019 12:54 PM > >> To: Eslimi, Dariush; MacDonald, Eric; Khalil, Ghada; Saul Wold; starlingx-discuss@lists.starlingx.io > >> Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages > >> Importance: High > >> > >> It's just an example, Dariush, of an internal change that would not impact an end user. Insert your > own > >> example if needed. :) > >> > >> Commit messages can provide plenty of context. If they are written well, of course, which the > reviewers > >> can verify / enforce. > >> > >> I'm not opposed to using SB and LP to document changes. But I don't think it's necessary to mandate > it > >> for every single change. > >> > >> brucej > >> > >> > >> -----Original Message----- > >> From: Eslimi, Dariush [mailto:Dariush.Eslimi@windriver.com] > >> Sent: Friday, September 13, 2019 8:53 AM > >> To: Jones, Bruce E <bruce.e.jones@intel.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; > >> Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- > >> discuss@lists.starlingx.io > >> Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages > >> > >> I would argue that is very bad example, why would a single project all of sudden wants to switch to > >> Python3? > >> Is this part of release goal to start using Python 3? Is this priority for the release? > >> > >> Small change need more context so code reviewers know why such a change is proposed. > >> > >> Dariush > >> > >> -----Original Message----- > >> From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] > >> Sent: September-13-19 11:37 AM > >> To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada > <Ghada.Khalil@windriver.com>; > >> Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io > >> Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages > >> > >> -1. Commit messages are update reasons and just as traceable. > >> > >> Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"? > >> > >> bruej > >> > >> -----Original Message----- > >> From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] > >> Sent: Friday, September 13, 2019 8:30 AM > >> To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx- > >> discuss@lists.starlingx.io > >> Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages > >> > >> +2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to. > >> > >>> -----Original Message----- > >>> From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] > >>> Sent: Friday, September 13, 2019 11:11 AM > >>> To: Saul Wold; starlingx-discuss@lists.starlingx.io > >>> Subject: Re: [Starlingx-discuss] Please Review: Requirements for > >>> commit messages > >>> > >>> Hi Saul, > >>> This was discussed previously and, as a community, we agreed that this > >>> is the guideline for starlingx submissions > >>> > >>> From > >>> https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines > >>> Link your review to a StoryBoard Story or Launchpad Bug For > >>> traceability, always link your code change to a story or bug. 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. > >>> > >>> > >>> 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). > >>> > >>> Regards, > >>> Ghada > >>> > >>> -----Original Message----- > >>> From: Saul Wold [mailto:sgw@linux.intel.com] > >>> Sent: Thursday, September 12, 2019 5:53 PM > >>> To: starlingx-discuss@lists.starlingx.io > >>> Subject: [Starlingx-discuss] Please Review: Requirements for commit > >>> messages > >>> > >>> > >>> StarlingX Folks: > >>> > >>> I would like to clarify the requirement or lack there of for having Bugs or Stories in commit > messages. > >>> There are patches that are clearly addressing bug fixes and those > >>> should have a Closes-Bug; there are commits that are clearly implementing features that should > have > >> the Story/Task tags. > >>> > >>> There are also commits that fall in between, they are not directly > >>> related to a given feature or have a bug filed, they are typically > >>> smaller and are fairly self-documenting or have good commit messages explaining why the change > is > >> needed, not just what the change does. > >>> > >>> Ultimately Closes-Bugs and Story tags will help reviewers and other > >>> get the infomration needed to create release notes, but we don't need > >>> to document every change like spelling, indentation, fixing compiler warnings in Release notes. > >>> > >>> I believe that we should have some flexibility in allowing for changes > >>> without related launchpad or story connections. This can help reduce > >>> the barrier to entry for small changes that community members may want to propose. > >>> > >>> Thoughts? > >>> > >>> Sau! > >>> > >>> _______________________________________________ > >>> Starlingx-discuss mailing list > >>> Starlingx-discuss@lists.starlingx.io > >>> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > >>> _______________________________________________ > >>> Starlingx-discuss mailing list > >>> Starlingx-discuss@lists.starlingx.io > >>> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > >> _______________________________________________ > >> Starlingx-discuss mailing list > >> Starlingx-discuss@lists.starlingx.io > >> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > >> _______________________________________________ > >> Starlingx-discuss mailing list > >> Starlingx-discuss@lists.starlingx.io > >> http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > > _______________________________________________ > > Starlingx-discuss mailing list > > Starlingx-discuss@lists.starlingx.io > > http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss > > > > _______________________________________________ > Starlingx-discuss mailing list > Starlingx-discuss@lists.starlingx.io > http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Ok, then my example for something that has no user impact is fixing spelling mistakes in comments :) Changing python has performance impact. Point taken that you are suggesting to have some freedom to have occasional commits with well written commit messages that are not toward a particular release related activity. Dariush -----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: September-13-19 12:54 PM To: Eslimi, Dariush <Dariush.Eslimi@windriver.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages It's just an example, Dariush, of an internal change that would not impact an end user. Insert your own example if needed. :) Commit messages can provide plenty of context. If they are written well, of course, which the reviewers can verify / enforce. I'm not opposed to using SB and LP to document changes. But I don't think it's necessary to mandate it for every single change. brucej -----Original Message----- From: Eslimi, Dariush [mailto:Dariush.Eslimi@windriver.com] Sent: Friday, September 13, 2019 8:53 AM To: Jones, Bruce E <bruce.e.jones@intel.com>; MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages I would argue that is very bad example, why would a single project all of sudden wants to switch to Python3? Is this part of release goal to start using Python 3? Is this priority for the release? Small change need more context so code reviewers know why such a change is proposed. Dariush -----Original Message----- From: Jones, Bruce E [mailto:bruce.e.jones@intel.com] Sent: September-13-19 11:37 AM To: MacDonald, Eric <Eric.MacDonald@windriver.com>; Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages -1. Commit messages are update reasons and just as traceable. Do we really need a SB entry for changes like "replace #!/usr/bin/python with #!/usr/bin/python3"? bruej -----Original Message----- From: MacDonald, Eric [mailto:Eric.MacDonald@windriver.com] Sent: Friday, September 13, 2019 8:30 AM To: Khalil, Ghada <Ghada.Khalil@windriver.com>; Saul Wold <sgw@linux.intel.com>; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages +2 Ghada's point. I'd like to avoid the slippery slope no update reason or traceability can lead to.
-----Original Message----- From: Khalil, Ghada [mailto:Ghada.Khalil@windriver.com] Sent: Friday, September 13, 2019 11:11 AM To: Saul Wold; starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] Please Review: Requirements for commit messages
Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions
From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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.
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).
Regards, Ghada
-----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages
StarlingX Folks:
I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags.
There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does.
Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes.
I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose.
Thoughts?
Sau!
_______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
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
I should also clarify that I am not suggesting a unique story for each commit. On the contrary, I personally like bigger scope stories with multiple tasks for the different commits. Even the tasks don't need to be unique per commit; multiple commits can link back to the same task. For example, fixing compile warnings as a prep for multi-OS support. This is one story with multiple tasks/commits. Anyway my 2 cents :) I'll give a chance to others to chime in. Ghada -----Original Message----- From: Khalil, Ghada Sent: Friday, September 13, 2019 11:11 AM To: 'Saul Wold'; starlingx-discuss@lists.starlingx.io Subject: RE: [Starlingx-discuss] Please Review: Requirements for commit messages Hi Saul, This was discussed previously and, as a community, we agreed that this is the guideline for starlingx submissions From https://wiki.openstack.org/wiki/StarlingX/CodeSubmissionGuidelines Link your review to a StoryBoard Story or Launchpad Bug For traceability, always link your code change to a story or bug. 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. 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). Regards, Ghada -----Original Message----- From: Saul Wold [mailto:sgw@linux.intel.com] Sent: Thursday, September 12, 2019 5:53 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] Please Review: Requirements for commit messages StarlingX Folks: I would like to clarify the requirement or lack there of for having Bugs or Stories in commit messages. There are patches that are clearly addressing bug fixes and those should have a Closes-Bug; there are commits that are clearly implementing features that should have the Story/Task tags. There are also commits that fall in between, they are not directly related to a given feature or have a bug filed, they are typically smaller and are fairly self-documenting or have good commit messages explaining why the change is needed, not just what the change does. Ultimately Closes-Bugs and Story tags will help reviewers and other get the infomration needed to create release notes, but we don't need to document every change like spelling, indentation, fixing compiler warnings in Release notes. I believe that we should have some flexibility in allowing for changes without related launchpad or story connections. This can help reduce the barrier to entry for small changes that community members may want to propose. Thoughts? Sau! _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
participants (7)
-
Cordoba Malibran, Erich
-
Eslimi, Dariush
-
Jeremy Stanley
-
Jones, Bruce E
-
Khalil, Ghada
-
MacDonald, Eric
-
Saul Wold