On 2019-02-27 17:10, Andrew Jeffery wrote:=

> On Wed, 27 Feb 20=
19, at 01:52, Joseph Reynolds wrote:
>> This is a proposal to improve OpenBMC communication =
and get better
>> =
;release notes.
>>
>> ** Preamble **
>>
>> Teams that use OpenBMC in other pro=
jects will not know OpenBMC as well
>> as the development community, and they will not know =
what is in each
>>&nbs=
p;release.  The main way for them to find out is by reading the releas=
e
>> notes.  =
;They will make decisions based on its contents.  That makes
>> the
=
>> release notes an important commun=
ication between the development
>> community and its end-users.
>>
=
>> We need to get better at communicating new and changed OpenBM=
C
>> functions. &=
nbsp;Doing so gives many benefits, including better release
=
>> notes
>> [1].

>>
>=
> ** The proposal **
>>
>> 1. A=
dopt a new practice to provide end-user impact statements when and
>> where it make sense to=
 do so.
>> 2. Beg=
in a project level change log to summarize user impacts.
>>
>> ** Details **
>>
>>&=
nbsp;How do these changes help connect the folks who contribute to OpenBMC<=
/font>
>> with the folks=
 who use it?  The main points are:
>> 1. Contributors write an "end-user impact" statem=
ent to notify users
>>=
 that something they might care about has changed.
=
>> 2. Community members use end-user=
 impact statements to create a change
>> log which summarizes changes they consider signific=
ant.
>> 3. Releas=
e planning summarizes the change log as an input to the
=
>> release
>> notes.
>>
>=
> Items in detail:
&=
gt;>
>> 1. Cre=
ate end-user impact statements.
>>
>> A=
n "end-user impact" statement summarizes each change from the point<=
/tt>
>> of
>> view of someone familiar with us=
ing the external interfaces.  It tells
>> them what they need to know about what chan=
ged from their point of
>=
> view,
>>&nbs=
p;so they know what to test, how to adapt, etc.
>>
>> When there is an impact, it should have details like:=

>> - Is there an end-us=
er impact (y/n)?
>>&nb=
sp;- Is this a new feature or function (where are the docs)?>> - Is this a bug fix?<=
/tt>
>> - What does the end-u=
ser need to know (one liner)?
>> These statements don't have to be perfect.  Any inklin=
g you can
>> prov=
ide
>> that there=
 is a user impact is helpful to the community.  The impact=

>> might change during the r=
elease as the design evolves.  Different
>> contributors will see different impacts. &n=
bsp;That's all normal and okay.
>>
>> A=
re the following end-user impacts?
>> - Change to phosphor-webui that affects the browser di=
splay?  Answer
>>=
 "no" if it doesn't affect usage, or "Yes" if the user will likely
>> notice
>> or care.
=
>> - Bug fix in fan control? Ans=
wer depends.  Answer "yes" if the bug
>> might
>> start a fire.
>> - Refactor code?  No
>> - New Redfish API?  Yes; new features=
 are positive user impacts.
=
>> - Adding new documentation?  No; although helpful, docs =
don't affect
>> t=
he
>> end-user's =
use of the external interfaces
>> - BMCWeb retires old and accepts new TLS encryption algori=
thms?  Yes,
>>&nb=
sp;it
>> affects =
how you can connect to the BMC
>> - Changes to phosphor-rest or to D-Bus APIs?  No, des=
pite their
>> imp=
ortance, these interfaces are technically internal to the BMC.  We
>> might want to doc=
ument user-impacts to these as well.
>> - Security fix?  Yes, probably, given today's c=
limate
>> Feel fr=
ee to come up with your own criteria, based on your estimation<=
br>>> of
>> an end-user.
>>
>> Writing an "end-user impact" statement bridges two worlds=
.  Folks who
>>&n=
bsp;work on the code may prefer to leave documentation for others or may
>> not<=
br>>> fully understand the impac=
t of their change on BMC operations.  And
>> nobody else may understand the change. &nb=
sp;So who should write the
&=
gt;> end-user
>&g=
t; impact statement?  Anyone who understands the change and how i=
t
>> impacts
>> end-users.  T=
hat could be developers, testers, or project managers.
<=
font size=3D"3" face=3D"" >>> Multiple people can contribute ove=
r time.  And it should be okay to
>> document an end-user impact in someone else's chan=
ge.
>>
=
>> It is important that all of t=
he end-user impact statements be
>> "findable".  Adding them as comments on selected =
GitHub issues is an
>>=
 obvious solution, and I suggest using the issue associated with the
>> code
>> change that caused the u=
ser impact. (We could use GitHub labels [8][9]
>> to mark issues which have user impact.)
>>
>> 2. Create a change log from end-use=
r impact statements.
>>=
;
>> Groups who c=
are about end-user impacts include testers, security
>> folks,
>> release managers, and others.  They ca=
n scan the issues, read the
=
>> impact
>>=
; statements, and use them to curate a change log [2] which lists all<=
/font>
>> changes that m=
ight be interesting to users.  Each change log entry
>> should have a brief description=
 of the impact (from the user's point
>> of
&=
gt;> view) with links back to the issue.  The change log could=
 be an
>> openbmc=

>> wiki page. &n=
bsp;(And yes, some people's job includes curating change
>> logs.)
>>
>> We should have a project-wide change log which captures al=
l impacts.
>> (It=
 is easy to ignore entries you don't care about.)  Anyone who cares
>> about a user imp=
act can add items to the change log.
>>
>>&n=
bsp;How is the change log useful?  Testers will use the change log to =
help
>> ensure te=
st coverage and add facts about where the test cases are
>> stored
>> and whether the tests passed.  Rel=
ease managers will use it to gauge
>> progress toward goals.  Security folks will cover=
 security changes.
>>&=
nbsp;Technical writers, etc.  Each will contribute significant facts a=
bout
>> their par=
t of the process, and the log is a place to organize links to>> demos, etc.
=
>>
>> 3. Use the change log to make release notes.
>>
>> The Release Planning work group [3] =
can refer to the change log as an
>> input to the Release Notes [1][4].  For example, =
multiple changes can
>>=
; be
>> merg=
ed, minor changes can be omitted, important changes can be
<=
tt>>> highlighted, etc.  Having=
 good release notes is a hallmark of a mature
>> development process.
>>
>> Let's be clear about this: Most users will ignore the =
release notes or
>>&nb=
sp;use it only to answer specific questions about bugs or features.  O=
nly
>> a
>> few will use it to lea=
rn more about new functions, changed functions
>> they have to adapt to, how to review test =
efforts, what security fixes
>> are included, etc.  They will make decisions based on i=
ts content.
>> Fo=
r
>> example, som=
e groups may use it as part of a software security
>> assurance

>> process [5].
>>
&=
gt;> ** Conclusion **
>>
>> Tha=
t's the proposal ... create end-user impact statements ...
<=
tt>>> summarize
<=
font size=3D"3" face=3D"" >>> them in a change log ... and massa=
ge that into release notes.  The
>> real
>> trick is to actually write end-user impact statements as the=
 work is
>> being=
 done.  We have the test team [6] and the security work group [7]
>> to help with that,=
 along with pressure from groups who use OpenBMC in
>> their projects.
>
> So, I think it's a reasonable proposal, however, I think there=
 needs to
> be
> more concrete descripti=
on of how I as a contributor go about this.
> There's
> a sort-of throw-away suggestion above that the user impac=
t descriptions
> sho=
uld go in "the github issue associated with the change" - I guess I<=
/tt>
> want
<=
font size=3D"3" face=3D"" >> to see some agreement that this is how=
 we're going to go about it. You

> probably also want to start hassling developers to actuall=
y write the
> impact=

> statement; while =
I don't expect anyone will be opposed to the idea,
> getting
> them to take it up is a separate problem (there may =
also be a problem
> =
of
> having a github=
 issue associated with the change to start with).

Thank you!

Here is the next level of detail:

1. Add the "change log process" to the CONTRIBUTING =
doc [101].
- Motivate the ne=
ed to document end-user impacts and for a change log,
        and show how these flow into t=
he release notes.
        - =
Provide guidance for the content of user impact statements.
=
        Give examples of impacts, non-impac=
ts, and end-users.
        -=
 Say where to document impacts (in github.com/openbmc/REPO/issues).<=
/tt>
2. Agree to use issues to doc=
ument user impact statements.  Understand
that any indication there is a user impact is helpful. &=
nbsp;Agree it is okay
to wri=
te a terse impact statement.  Agree that mentioning @changelog<=
/tt>
with no other explanation means you=
 want someone else to write the
impact statement.  Agree it is okay for someone other than the dev=
eloper
to write impact state=
ments.  Agree that if you write @changelog and
nobody takes any action, then nobody cares about yo=
ur change, and that's
okay.<=
/font>

3. Create a GitHub openb=
mc user called "changelog".  Then contributors
can @mention [102] @changelog in the issue that des=
cribes the user
impacts,
and all issues that describe us=
er impacts can be found.  I had thought
to create a new label [8][9] called "User impact" for thi=
s purpose, but
GitHub permis=
sions do not allow most users to add labels.

4. Create the Change Log wiki here:
https://github.com/openbmc/openbmc/wiki/c=
hangelog
and begin to po=
pulate it with user impact.

I am interested in this a way to track the software development process=
.
Specifically, I would crea=
te user impact statements and changelog
entries for:
- R=
elease 2.7 work items as they complete, tracked here: [103].- Functions being tracked by the test work=
 group [104].
- Security imp=
acts [105].

- Joseph

[101]: https=
://github.com/openbmc/docs/blob/master/CONTRIBUTING.md
<=
tt>[102]: https://help.github.c=
om/en/articles/mentions-on-github-pages
[103]: https://github.com/openbmc/openbmc/labels/=
Release2.7
[104]: https://github.com/openbmc/openbmc/wiki/Test-work-group
[105]:
https://github.com/openbmc/openbmc/wiki/Security-working-group#curre=
nt-development-work-with-security-impact

> Andrew
>
>>
>> - Joseph Reynolds<=
/font>
>>
=
>> [1]: https://en.m.wikipedia.org/=
wiki/Release_notes
>&=
gt; [2]: https://en.m.wikipedia.org/wiki/Changelog
>> [3]: https://github=
.com/openbmc/openbmc/wiki/Release-Planning
>> [4]:
>> https://github.com/openbmc/=
docs/blob/master/release/release-notes.md
>> [5]: https://en.wikipedia.org/=
wiki/Software_security_assurance
>> [6]: https://github.com/openbmc/openbmc/w=
iki/Test-work-group
>=
> [7]: https://github.com/openbmc/openbmc/wiki/Se=
curity-working-group
>=
;> [8]: https://help.github.com/en/articles/about-labels
>> [9]: https://github=
.com/openbmc/openbmc/labels
>>
>>=