[Proposal] End-user impacts and change log + details

[Joseph Reynolds]

On 2019-03-01 15:22, Joseph Reynolds wrote:
> On 2019-02-27 17:10, Andrew Jeffery wrote:
>> On Wed, 27 Feb 2019, 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 projects will not know OpenBMC as 
>>> well
>>> as the development community, and they will not know what is in each
>>> release.  The main way for them to find out is by reading the release
>>> notes.  They will make decisions based on its contents.  That makes 
>>> the
>>> release notes an important communication between the development
>>> community and its end-users.
>>> 
>>> We need to get better at communicating new and changed OpenBMC
>>> functions.  Doing so gives many benefits, including better release 
>>> notes
>>> [1].
>>> 
>>> ** The proposal **
>>> 
>>> 1. Adopt a new practice to provide end-user impact statements when 
>>> and
>>> where it make sense to do so.
>>> 2. Begin a project level change log to summarize user impacts.
>>> 
>>> ** Details **
>>> 

...snip...

I am no longer pursuing end-user impacts statements in each issue at 
this time. Instead I create a work-in-progress wiki.  I'll start a 
separate email thread to announce that.

>>> 
>>> 2. Create a change log from end-user impact statements.
>>> 
>>> Groups who care about end-user impacts include testers, security 
>>> folks,
>>> release managers, and others.  They can scan the issues, read the 
>>> impact
>>> statements, and use them to curate a change log [2] which lists all
>>> changes that might be interesting to users.  Each change log entry
>>> should have a brief description of the impact (from the user's point 
>>> of
>>> view) with links back to the issue.  The change log could be an 
>>> openbmc
>>> wiki page.  (And yes, some people's job includes curating change 
>>> logs.)
>>> 
>>> We should have a project-wide change log which captures all impacts.
>>> (It is easy to ignore entries you don't care about.)  Anyone who 
>>> cares
>>> about a user impact can add items to the change log.
>>> 
>>> How is the change log useful?  Testers will use the change log to 
>>> help
>>> ensure test coverage and add facts about where the test cases are 
>>> stored
>>> and whether the tests passed.  Release managers will use it to gauge
>>> progress toward goals.  Security folks will cover security changes.
>>> Technical writers, etc.  Each will contribute significant facts about
>>> their part of the process, and the log is a place to organize links 
>>> to
>>> demos, etc.
>>> 
>>> 3. Use the change log to make release notes.

...snip...

> 
> Here is the next level of detail:
> 
> 1. Add the "change log process" to the CONTRIBUTING doc [101].
>  - Motivate the need to document end-user impacts and for a change log,
>    and show how these flow into the release notes.
>  - Provide guidance for the content of user impact statements.
>    Give examples of impacts, non-impacts, and end-users.
>  - Say where to document impacts (in github.com/openbmc/REPO/issues).

...snip...

> 4. Create the Change Log wiki here:
> https://github.com/openbmc/openbmc/wiki/changelog
> and begin to populate it with user impact.

This is done.  I'll start a new email thread to announce it.

- Joseph

> I am interested in this a way to track the software development
> process.  Specifically, I would create user impact statements and
> changelog entries for:
>  - Release 2.7 work items as they complete, tracked here: [103].
>  - Functions being tracked by the test work group [104].
>  - Security impacts [105].
> 
> - Joseph
> 
> [101]: https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md
> [102]: https://help.github.com/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#current-development-work-with-security-impact
> 
>> Andrew
>> 
>>> 
>>> - Joseph Reynolds
>>> 
>>> [1]: https://en.m.wikipedia.org/wiki/Release_notes
>>> [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/wiki/Test-work-group
>>> [7]: https://github.com/openbmc/openbmc/wiki/Security-working-group
>>> [8]: https://help.github.com/en/articles/about-labels
>>> [9]: https://github.com/openbmc/openbmc/labels
>>> 
>>>