<div class="socmaildefaultfont" dir="ltr" style="font-family:Arial, Helvetica, sans-serif;font-size:10.5pt" ><div dir="ltr" >Found it as useful, And from my perspective, not all git-hub issues should have user impact.</div>
<div dir="ltr" >Because some time git-hub issue may not be a bug / non recreative / user error too.</div>
<div dir="ltr" > </div>
<div dir="ltr" >I feel only if the issue is a valid one where code changes / design changes happens then</div>
<div dir="ltr" >git-hub should automatically ask to populate user-impact statement and pull that in release notes automatically.</div>
<div dir="ltr" > </div>
<div dir="ltr" >May be we can request git-hub to check the user impact field / property is populated for issues where a commit is</div>
<div dir="ltr" >getting merged.</div>
<div dir="ltr" > </div>
<div dir="ltr" >With regards,</div>
<div dir="ltr" >Sivas</div>
<div dir="ltr" > </div>
<div dir="ltr" > </div>
<blockquote data-history-content-modified="1" dir="ltr" style="border-left:solid #aaaaaa 2px; margin-left:5px; padding-left:5px; direction:ltr; margin-right:0px" >----- Original message -----<br>From: Joseph Reynolds <jrey@linux.ibm.com><br>Sent by: "openbmc" <openbmc-bounces+sivas.srr=in.ibm.com@lists.ozlabs.org><br>To: Andrew Jeffery <andrew@aj.id.au><br>Cc: openbmc@lists.ozlabs.org, openbmc <openbmc-bounces+jrey=linux.ibm.com@lists.ozlabs.org><br>Subject: Re: [Proposal] End-user impacts and change log + details<br>Date: Sat, Mar 2, 2019 2:47 AM<br> <br><tt><font size="3" face="" >On 2019-02-27 17:10, Andrew Jeffery wrote:</font></tt><br><tt><font size="3" face="" >> On Wed, 27 Feb 2019, at 01:52, Joseph Reynolds wrote:</font></tt><br><tt><font size="3" face="" >>> This is a proposal to improve OpenBMC communication and get better</font></tt><br><tt><font size="3" face="" >>> release notes.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> ** Preamble **</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> Teams that use OpenBMC in other projects will not know OpenBMC as well</font></tt><br><tt><font size="3" face="" >>> as the development community, and they will not know what is in each</font></tt><br><tt><font size="3" face="" >>> release. The main way for them to find out is by reading the release</font></tt><br><tt><font size="3" face="" >>> notes. They will make decisions based on its contents. That makes</font></tt><br><tt><font size="3" face="" >>> the</font></tt><br><tt><font size="3" face="" >>> release notes an important communication between the development</font></tt><br><tt><font size="3" face="" >>> community and its end-users.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> We need to get better at communicating new and changed OpenBMC</font></tt><br><tt><font size="3" face="" >>> functions. Doing so gives many benefits, including better release</font></tt><br><tt><font size="3" face="" >>> notes</font></tt><br><tt><font size="3" face="" >>> [1].</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> ** The proposal **</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> 1. Adopt a new practice to provide end-user impact statements when and</font></tt><br><tt><font size="3" face="" >>> where it make sense to do so.</font></tt><br><tt><font size="3" face="" >>> 2. Begin a project level change log to summarize user impacts.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> ** Details **</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> How do these changes help connect the folks who contribute to OpenBMC</font></tt><br><tt><font size="3" face="" >>> with the folks who use it? The main points are:</font></tt><br><tt><font size="3" face="" >>> 1. Contributors write an "end-user impact" statement to notify users</font></tt><br><tt><font size="3" face="" >>> that something they might care about has changed.</font></tt><br><tt><font size="3" face="" >>> 2. Community members use end-user impact statements to create a change</font></tt><br><tt><font size="3" face="" >>> log which summarizes changes they consider significant.</font></tt><br><tt><font size="3" face="" >>> 3. Release planning summarizes the change log as an input to the</font></tt><br><tt><font size="3" face="" >>> release</font></tt><br><tt><font size="3" face="" >>> notes.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> Items in detail:</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> 1. Create end-user impact statements.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> An "end-user impact" statement summarizes each change from the point</font></tt><br><tt><font size="3" face="" >>> of</font></tt><br><tt><font size="3" face="" >>> view of someone familiar with using the external interfaces. It tells</font></tt><br><tt><font size="3" face="" >>> them what they need to know about what changed from their point of</font></tt><br><tt><font size="3" face="" >>> view,</font></tt><br><tt><font size="3" face="" >>> so they know what to test, how to adapt, etc.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> When there is an impact, it should have details like:</font></tt><br><tt><font size="3" face="" >>> - Is there an end-user impact (y/n)?</font></tt><br><tt><font size="3" face="" >>> - Is this a new feature or function (where are the docs)?</font></tt><br><tt><font size="3" face="" >>> - Is this a bug fix?</font></tt><br><tt><font size="3" face="" >>> - What does the end-user need to know (one liner)?</font></tt><br><tt><font size="3" face="" >>> These statements don't have to be perfect. Any inkling you can</font></tt><br><tt><font size="3" face="" >>> provide</font></tt><br><tt><font size="3" face="" >>> that there is a user impact is helpful to the community. The impact</font></tt><br><tt><font size="3" face="" >>> might change during the release as the design evolves. Different</font></tt><br><tt><font size="3" face="" >>> contributors will see different impacts. That's all normal and okay.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> Are the following end-user impacts?</font></tt><br><tt><font size="3" face="" >>> - Change to phosphor-webui that affects the browser display? Answer</font></tt><br><tt><font size="3" face="" >>> "no" if it doesn't affect usage, or "Yes" if the user will likely</font></tt><br><tt><font size="3" face="" >>> notice</font></tt><br><tt><font size="3" face="" >>> or care.</font></tt><br><tt><font size="3" face="" >>> - Bug fix in fan control? Answer depends. Answer "yes" if the bug</font></tt><br><tt><font size="3" face="" >>> might</font></tt><br><tt><font size="3" face="" >>> start a fire.</font></tt><br><tt><font size="3" face="" >>> - Refactor code? No</font></tt><br><tt><font size="3" face="" >>> - New Redfish API? Yes; new features are positive user impacts.</font></tt><br><tt><font size="3" face="" >>> - Adding new documentation? No; although helpful, docs don't affect</font></tt><br><tt><font size="3" face="" >>> the</font></tt><br><tt><font size="3" face="" >>> end-user's use of the external interfaces</font></tt><br><tt><font size="3" face="" >>> - BMCWeb retires old and accepts new TLS encryption algorithms? Yes,</font></tt><br><tt><font size="3" face="" >>> it</font></tt><br><tt><font size="3" face="" >>> affects how you can connect to the BMC</font></tt><br><tt><font size="3" face="" >>> - Changes to phosphor-rest or to D-Bus APIs? No, despite their</font></tt><br><tt><font size="3" face="" >>> importance, these interfaces are technically internal to the BMC. We</font></tt><br><tt><font size="3" face="" >>> might want to document user-impacts to these as well.</font></tt><br><tt><font size="3" face="" >>> - Security fix? Yes, probably, given today's climate</font></tt><br><tt><font size="3" face="" >>> Feel free to come up with your own criteria, based on your estimation</font></tt><br><tt><font size="3" face="" >>> of</font></tt><br><tt><font size="3" face="" >>> an end-user.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> Writing an "end-user impact" statement bridges two worlds. Folks who</font></tt><br><tt><font size="3" face="" >>> work on the code may prefer to leave documentation for others or may</font></tt><br><tt><font size="3" face="" >>> not</font></tt><br><tt><font size="3" face="" >>> fully understand the impact of their change on BMC operations. And</font></tt><br><tt><font size="3" face="" >>> nobody else may understand the change. So who should write the</font></tt><br><tt><font size="3" face="" >>> end-user</font></tt><br><tt><font size="3" face="" >>> impact statement? Anyone who understands the change and how it</font></tt><br><tt><font size="3" face="" >>> impacts</font></tt><br><tt><font size="3" face="" >>> end-users. That could be developers, testers, or project managers.</font></tt><br><tt><font size="3" face="" >>> Multiple people can contribute over time. And it should be okay to</font></tt><br><tt><font size="3" face="" >>> document an end-user impact in someone else's change.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> It is important that all of the end-user impact statements be</font></tt><br><tt><font size="3" face="" >>> "findable". Adding them as comments on selected GitHub issues is an</font></tt><br><tt><font size="3" face="" >>> obvious solution, and I suggest using the issue associated with the</font></tt><br><tt><font size="3" face="" >>> code</font></tt><br><tt><font size="3" face="" >>> change that caused the user impact. (We could use GitHub labels [8][9]</font></tt><br><tt><font size="3" face="" >>> to mark issues which have user impact.)</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> 2. Create a change log from end-user impact statements.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> Groups who care about end-user impacts include testers, security</font></tt><br><tt><font size="3" face="" >>> folks,</font></tt><br><tt><font size="3" face="" >>> release managers, and others. They can scan the issues, read the</font></tt><br><tt><font size="3" face="" >>> impact</font></tt><br><tt><font size="3" face="" >>> statements, and use them to curate a change log [2] which lists all</font></tt><br><tt><font size="3" face="" >>> changes that might be interesting to users. Each change log entry</font></tt><br><tt><font size="3" face="" >>> should have a brief description of the impact (from the user's point</font></tt><br><tt><font size="3" face="" >>> of</font></tt><br><tt><font size="3" face="" >>> view) with links back to the issue. The change log could be an</font></tt><br><tt><font size="3" face="" >>> openbmc</font></tt><br><tt><font size="3" face="" >>> wiki page. (And yes, some people's job includes curating change</font></tt><br><tt><font size="3" face="" >>> logs.)</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> We should have a project-wide change log which captures all impacts.</font></tt><br><tt><font size="3" face="" >>> (It is easy to ignore entries you don't care about.) Anyone who cares</font></tt><br><tt><font size="3" face="" >>> about a user impact can add items to the change log.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> How is the change log useful? Testers will use the change log to help</font></tt><br><tt><font size="3" face="" >>> ensure test coverage and add facts about where the test cases are</font></tt><br><tt><font size="3" face="" >>> stored</font></tt><br><tt><font size="3" face="" >>> and whether the tests passed. Release managers will use it to gauge</font></tt><br><tt><font size="3" face="" >>> progress toward goals. Security folks will cover security changes.</font></tt><br><tt><font size="3" face="" >>> Technical writers, etc. Each will contribute significant facts about</font></tt><br><tt><font size="3" face="" >>> their part of the process, and the log is a place to organize links to</font></tt><br><tt><font size="3" face="" >>> demos, etc.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> 3. Use the change log to make release notes.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> The Release Planning work group [3] can refer to the change log as an</font></tt><br><tt><font size="3" face="" >>> input to the Release Notes [1][4]. For example, multiple changes can</font></tt><br><tt><font size="3" face="" >>> be</font></tt><br><tt><font size="3" face="" >>> merged, minor changes can be omitted, important changes can be</font></tt><br><tt><font size="3" face="" >>> highlighted, etc. Having good release notes is a hallmark of a mature</font></tt><br><tt><font size="3" face="" >>> development process.</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> Let's be clear about this: Most users will ignore the release notes or</font></tt><br><tt><font size="3" face="" >>> use it only to answer specific questions about bugs or features. Only</font></tt><br><tt><font size="3" face="" >>> a</font></tt><br><tt><font size="3" face="" >>> few will use it to learn more about new functions, changed functions</font></tt><br><tt><font size="3" face="" >>> they have to adapt to, how to review test efforts, what security fixes</font></tt><br><tt><font size="3" face="" >>> are included, etc. They will make decisions based on its content.</font></tt><br><tt><font size="3" face="" >>> For</font></tt><br><tt><font size="3" face="" >>> example, some groups may use it as part of a software security</font></tt><br><tt><font size="3" face="" >>> assurance</font></tt><br><tt><font size="3" face="" >>> process [5].</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> ** Conclusion **</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> That's the proposal ... create end-user impact statements ...</font></tt><br><tt><font size="3" face="" >>> summarize</font></tt><br><tt><font size="3" face="" >>> them in a change log ... and massage that into release notes. The</font></tt><br><tt><font size="3" face="" >>> real</font></tt><br><tt><font size="3" face="" >>> trick is to actually write end-user impact statements as the work is</font></tt><br><tt><font size="3" face="" >>> being done. We have the test team [6] and the security work group [7]</font></tt><br><tt><font size="3" face="" >>> to help with that, along with pressure from groups who use OpenBMC in</font></tt><br><tt><font size="3" face="" >>> their projects.</font></tt><br><tt><font size="3" face="" >></font></tt><br><tt><font size="3" face="" >> So, I think it's a reasonable proposal, however, I think there needs to</font></tt><br><tt><font size="3" face="" >> be</font></tt><br><tt><font size="3" face="" >> more concrete description of how I as a contributor go about this.</font></tt><br><tt><font size="3" face="" >> There's</font></tt><br><tt><font size="3" face="" >> a sort-of throw-away suggestion above that the user impact descriptions</font></tt><br><tt><font size="3" face="" >> should go in "the github issue associated with the change" - I guess I</font></tt><br><tt><font size="3" face="" >> want</font></tt><br><tt><font size="3" face="" >> to see some agreement that this is how we're going to go about it. You</font></tt><br><tt><font size="3" face="" >> probably also want to start hassling developers to actually write the</font></tt><br><tt><font size="3" face="" >> impact</font></tt><br><tt><font size="3" face="" >> statement; while I don't expect anyone will be opposed to the idea,</font></tt><br><tt><font size="3" face="" >> getting</font></tt><br><tt><font size="3" face="" >> them to take it up is a separate problem (there may also be a problem</font></tt><br><tt><font size="3" face="" >> of</font></tt><br><tt><font size="3" face="" >> having a github issue associated with the change to start with).</font></tt><br><br><tt><font size="3" face="" >Thank you!</font></tt><br><br><tt><font size="3" face="" >Here is the next level of detail:</font></tt><br><br><tt><font size="3" face="" >1. Add the "change log process" to the CONTRIBUTING doc [101].</font></tt><br><tt><font size="3" face="" >- Motivate the need to document end-user impacts and for a change log,</font></tt>
<ul style="padding-left: 12pt; margin-left: 0px; list-style-type: none;" > <li><tt><font size="3" face="" >and show how these flow into the release notes.</font></tt><br> <tt><font size="3" face="" >- Provide guidance for the content of user impact statements.</font></tt><br> <tt><font size="3" face="" >Give examples of impacts, non-impacts, and end-users.</font></tt><br> <tt><font size="3" face="" >- Say where to document impacts (in github.com/openbmc/REPO/issues).</font></tt></li></ul><tt><font size="3" face="" >2. Agree to use issues to document user impact statements. Understand</font></tt><br><tt><font size="3" face="" >that any indication there is a user impact is helpful. Agree it is okay</font></tt><br><tt><font size="3" face="" >to write a terse impact statement. Agree that mentioning @changelog</font></tt><br><tt><font size="3" face="" >with no other explanation means you want someone else to write the</font></tt><br><tt><font size="3" face="" >impact statement. Agree it is okay for someone other than the developer</font></tt><br><tt><font size="3" face="" >to write impact statements. Agree that if you write @changelog and</font></tt><br><tt><font size="3" face="" >nobody takes any action, then nobody cares about your change, and that's</font></tt><br><tt><font size="3" face="" >okay.</font></tt><br><br><tt><font size="3" face="" >3. Create a GitHub openbmc user called "changelog". Then contributors</font></tt><br><tt><font size="3" face="" >can @mention [102] @changelog in the issue that describes the user</font></tt><br><tt><font size="3" face="" >impacts,</font></tt><br><tt><font size="3" face="" >and all issues that describe user impacts can be found. I had thought</font></tt><br><tt><font size="3" face="" >to create a new label [8][9] called "User impact" for this purpose, but</font></tt><br><tt><font size="3" face="" >GitHub permissions do not allow most users to add labels.</font></tt><br><br><tt><font size="3" face="" >4. Create the Change Log wiki here:</font></tt><br><tt><font size="3" face="" ><a href="https://github.com/openbmc/openbmc/wiki/changelog" target="_blank">https://github.com/openbmc/openbmc/wiki/changelog</a></font></tt><br><tt><font size="3" face="" >and begin to populate it with user impact.</font></tt><br><br><tt><font size="3" face="" >I am interested in this a way to track the software development process.</font></tt><br><tt><font size="3" face="" >Specifically, I would create user impact statements and changelog</font></tt><br><tt><font size="3" face="" >entries for:</font></tt><br><tt><font size="3" face="" >- Release 2.7 work items as they complete, tracked here: [103].</font></tt><br><tt><font size="3" face="" >- Functions being tracked by the test work group [104].</font></tt><br><tt><font size="3" face="" >- Security impacts [105].</font></tt><br><br><tt><font size="3" face="" >- Joseph</font></tt><br><br><tt><font size="3" face="" >[101]: <a href="https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md" target="_blank">https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md</a></font></tt><br><tt><font size="3" face="" >[102]: <a href="https://help.github.com/en/articles/mentions-on-github-pages" target="_blank">https://help.github.com/en/articles/mentions-on-github-pages</a></font></tt><br><tt><font size="3" face="" >[103]: <a href="https://github.com/openbmc/openbmc/labels/Release2.7" target="_blank">https://github.com/openbmc/openbmc/labels/Release2.7</a></font></tt><br><tt><font size="3" face="" >[104]: <a href="https://github.com/openbmc/openbmc/wiki/Test-work-group" target="_blank">https://github.com/openbmc/openbmc/wiki/Test-work-group</a></font></tt><br><tt><font size="3" face="" >[105]:</font></tt><br><tt><font size="3" face="" ><a href="https://github.com/openbmc/openbmc/wiki/Security-working-group#current-development-work-with-security-impact" target="_blank">https://github.com/openbmc/openbmc/wiki/Security-working-group#current-development-work-with-security-impact</a></font></tt><br><br><tt><font size="3" face="" >> Andrew</font></tt><br><tt><font size="3" face="" >></font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> - Joseph Reynolds</font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>> [1]: <a href="https://en.m.wikipedia.org/wiki/Release_notes" target="_blank">https://en.m.wikipedia.org/wiki/Release_notes</a></font></tt><br><tt><font size="3" face="" >>> [2]: <a href="https://en.m.wikipedia.org/wiki/Changelog" target="_blank">https://en.m.wikipedia.org/wiki/Changelog</a></font></tt><br><tt><font size="3" face="" >>> [3]: <a href="https://github.com/openbmc/openbmc/wiki/Release-Planning" target="_blank">https://github.com/openbmc/openbmc/wiki/Release-Planning</a></font></tt><br><tt><font size="3" face="" >>> [4]:</font></tt><br><tt><font size="3" face="" >>> <a href="https://github.com/openbmc/docs/blob/master/release/release-notes.md" target="_blank">https://github.com/openbmc/docs/blob/master/release/release-notes.md</a></font></tt><br><tt><font size="3" face="" >>> [5]: <a href="https://en.wikipedia.org/wiki/Software_security_assurance" target="_blank">https://en.wikipedia.org/wiki/Software_security_assurance</a></font></tt><br><tt><font size="3" face="" >>> [6]: <a href="https://github.com/openbmc/openbmc/wiki/Test-work-group" target="_blank">https://github.com/openbmc/openbmc/wiki/Test-work-group</a></font></tt><br><tt><font size="3" face="" >>> [7]: <a href="https://github.com/openbmc/openbmc/wiki/Security-working-group" target="_blank">https://github.com/openbmc/openbmc/wiki/Security-working-group</a></font></tt><br><tt><font size="3" face="" >>> [8]: <a href="https://help.github.com/en/articles/about-labels" target="_blank">https://help.github.com/en/articles/about-labels</a></font></tt><br><tt><font size="3" face="" >>> [9]: <a href="https://github.com/openbmc/openbmc/labels" target="_blank">https://github.com/openbmc/openbmc/labels</a></font></tt><br><tt><font size="3" face="" >>></font></tt><br><tt><font size="3" face="" >>></font></tt><br> </blockquote>
<div dir="ltr" > </div></div><BR>