[Starlingx-discuss] [docs] [meeting] Docs team notes 09-Jun-21
Hello all, Here are this week's docs team meeting minutes (short form). Details in [2]. Join us if you have interest in StarlingX docs! We meet on Wednesdays 12:30 PST. [1] Call logistics: https://wiki.openstack.org/wiki/Starlingx/Meetings [2] Tracking Etherpad: https://etherpad.openstack.org/p/stx-documentation thanks, Mary Camp ========== 09-Jun-21 All -- reviews merged since last meeting: 22 All -- bug status -- 17 total - team agrees to defer all low priority LP until the upstreaming effort is completed. Status/questions/opens Several reviewers are pressing for changes in commit messages - ie, where is the task/story info, why are they so long? Unclear why they are invested in the commit messages. Do we need to push back on this? Create "template" for commit messages for future updates. Add to parking lot for retrospective. How to address the gap between WR Jira tickets and LP - Story/Task info, without having to replicate all the info in 2 systems. Is there a reason why we can't reference Jira numbers in the commit messages? This is a question for Greg.
On 2021-06-10 00:33:26 +0000 (+0000), Camp, MaryX wrote: [...]
How to address the gap between WR Jira tickets and LP - Story/Task info, without having to replicate all the info in 2 systems. Is there a reason why we can't reference Jira numbers in the commit messages? This is a question for Greg.
I'm not Greg, but still curious. If a non-WR-employed contributor, aspiring contributor, user, et cetera is reviewing a change or looking at a commit in Git history which references a Jira ticket, how do they obtain the content of that ticket so they have proper context? Are those tickets publicly accessible? -- Jeremy Stanley
Hi Jeremy, that is exactly the issue we were discussing. Sometimes the context is simply "a developer emailed the docs team to change this guide on line 23 from A to B." If the commit message has the necessary details about the change, could the Jira number be just an identifier? Or does having a Jira number send the message that a non-public system is being used? In the example above, the simple change is opened as a Jira ticket and then is copied into LP to be linked in the commit message. We were chatting about alternatives, because no one wants to update/track info in 2 systems if there's a more efficient method. Appreciate your input -- good to know someone reads the docs meeting notes 😊 thanks, Mary Camp Kelly Services Technical Writer | maryx.camp@intel.com -----Original Message----- From: Jeremy Stanley <fungi@yuggoth.org> Sent: Wednesday, June 9, 2021 9:19 PM To: starlingx-discuss@lists.starlingx.io Subject: Re: [Starlingx-discuss] [docs] [meeting] Docs team notes 09-Jun-21 On 2021-06-10 00:33:26 +0000 (+0000), Camp, MaryX wrote: [...]
How to address the gap between WR Jira tickets and LP - Story/Task info, without having to replicate all the info in 2 systems. Is there a reason why we can't reference Jira numbers in the commit messages? This is a question for Greg.
I'm not Greg, but still curious. If a non-WR-employed contributor, aspiring contributor, user, et cetera is reviewing a change or looking at a commit in Git history which references a Jira ticket, how do they obtain the content of that ticket so they have proper context? Are those tickets publicly accessible? -- Jeremy Stanley
On 2021-06-10 02:55:33 +0000 (+0000), Camp, MaryX wrote: [...]
Sometimes the context is simply "a developer emailed the docs team to change this guide on line 23 from A to B." If the commit message has the necessary details about the change, could the Jira number be just an identifier? Or does having a Jira number send the message that a non-public system is being used?
In the example above, the simple change is opened as a Jira ticket and then is copied into LP to be linked in the commit message. We were chatting about alternatives, because no one wants to update/track info in 2 systems if there's a more efficient method. [...]
It's more about separating the proprietary product (Titanium Cloud, I guess?) defect tracking from the community open source development process which should, ideally, be independent of it. As the project hopefully grows and contributor affiliations diverge over time, what constitutes a bug in one company's product doesn't necessarily equal a bug in the open source software on which it's based. When working on a solution upstream, the contributors from WR will need to be able to articulate to the rest of the community what the perceived defect is anyway, for example by describing it in a new public bug report or within the commit message. Any time I look at a commit which references a private or otherwise undocumented tracking system, I find myself wondering what additional information is hidden there which I'm not sufficiently privileged to read. It doesn't benefit the general community for the open source project to include references to information in a private product tracking system, but does sow seeds of suspicion and imply that not all contributors are on equal footing when participating in the project (even if that's not really the case). On the other hand, many trackers (and I'm guessing Jira is no exception) have functionality for indicating when something is being addressed elsewhere, perhaps as a URL to the public StarlingX bug report. Something like that would still allow WR support staff and customers to directly follow the public work which is happening to address a particular problem, without unnecessarily embedding private references into it. If you do want to be able to reference private trackers for products within your public source code and commit metadata, you'll want to think hard about how you plan to support that workflow in the future when multiple companies have products based on that project, including how to disambiguate WR Jira IDs from OtherCompany Jira IDs without creating even more confusion. -- Jeremy Stanley
How to address the gap between WR Jira tickets and LP - Story/Task info, without having to replicate all the info in 2 systems. Is there a reason why we can't reference Jira numbers in the commit messages? This is a question for Greg.
For internal wind river types generating bugs on docs, we can remind people that if it is a problem that is in the upstream starlingx docs, that they should be generating a starlingx LP. And then ONLY use the LP; no internal WR JIRA would be created. If the internal WR JIRA is already created ... not sure we can do much other than duplicate the info in an LP. Greg. -----Original Message----- From: Camp, MaryX <maryx.camp@intel.com> Sent: Wednesday, June 9, 2021 8:33 PM To: starlingx-discuss@lists.starlingx.io Subject: [Starlingx-discuss] [docs] [meeting] Docs team notes 09-Jun-21 [Please note: This e-mail is from an EXTERNAL e-mail address] Hello all, Here are this week's docs team meeting minutes (short form). Details in [2]. Join us if you have interest in StarlingX docs! We meet on Wednesdays 12:30 PST. [1] Call logistics: https://wiki.openstack.org/wiki/Starlingx/Meetings [2] Tracking Etherpad: https://etherpad.openstack.org/p/stx-documentation thanks, Mary Camp ========== 09-Jun-21 All -- reviews merged since last meeting: 22 All -- bug status -- 17 total - team agrees to defer all low priority LP until the upstreaming effort is completed. Status/questions/opens Several reviewers are pressing for changes in commit messages - ie, where is the task/story info, why are they so long? Unclear why they are invested in the commit messages. Do we need to push back on this? Create "template" for commit messages for future updates. Add to parking lot for retrospective. How to address the gap between WR Jira tickets and LP - Story/Task info, without having to replicate all the info in 2 systems. Is there a reason why we can't reference Jira numbers in the commit messages? This is a question for Greg. _______________________________________________ Starlingx-discuss mailing list Starlingx-discuss@lists.starlingx.io http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss
participants (3)
-
Camp, MaryX
-
Jeremy Stanley
-
Waines, Greg