Skip to contentSkip to conversation

End-user impacts and change log + details

Proposal Joseph Reynolds 3 participants 4 messages Mar 1, 2019 – Apr 4, 2019

lore
Share & tools
lore
#0 lore raw
Quoted 137 lines · Andrew Jeffery
Quoted 127 lines · Joseph Reynolds

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 **

How do these changes help connect the folks who contribute to OpenBMC with the folks who use it? The main points are:
1. Contributors write an "end-user impact" statement 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 significant.
3. Release planning summarizes the change log as an input to the release notes.

Items in detail:

1. Create end-user impact statements.

An "end-user impact" statement summarizes each change from the point of view of someone familiar with using the external interfaces. It tells them what they need to know about what changed from their point of view, so they know what to test, how to adapt, etc.

When there is an impact, it should have details like:
- Is there an end-user impact (y/n)?
- Is this a new feature or function (where are the docs)?
- Is this a bug fix?
- What does the end-user need to know (one liner)?
These statements don't have to be perfect. Any inkling you can provide that there is a user impact is helpful to the community. The impact might change during the release as the design evolves. Different contributors will see different impacts. That's all normal and okay.

Are the following end-user impacts?
- Change to phosphor-webui that affects the browser display? Answer "no" if it doesn't affect usage, or "Yes" if the user will likely notice or care.
- Bug fix in fan control? Answer 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 the
end-user's use of the external interfaces
- BMCWeb retires old and accepts new TLS encryption algorithms? Yes, it
affects how you can connect to the BMC
- Changes to phosphor-rest or to D-Bus APIs? No, despite their importance, these interfaces are technically internal to the BMC. We might want to document user-impacts to these as well.
- Security fix? Yes, probably, given today's climate
Feel free to come up with your own criteria, based on your estimation of an end-user.

Writing an "end-user impact" statement bridges two worlds. Folks who work on the code may prefer to leave documentation for others or may not fully understand the impact of their change on BMC operations. And nobody else may understand the change. So who should write the end-user impact statement? Anyone who understands the change and how it impacts end-users. That could be developers, testers, or project managers. Multiple people can contribute over time. And it should be okay to document an end-user impact in someone else's change.

It is important that all of the 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 user impact. (We could use GitHub labels [8][9] to mark issues which have user impact.)

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.

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 merged, minor changes can be omitted, important changes can be 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 use it only to answer specific questions about bugs or features. Only a few will use it to learn 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 its content. For example, some groups may use it as part of a software security assurance process [5].

Quoted 8 lines

** Conclusion **

That's the proposal ... create end-user impact statements ... summarize them in a change log ... and massage 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.

Quoted 9 lines

So, I think it's a reasonable proposal, however, I think there needs to be more concrete description of how I as a contributor go about this. There's a sort-of throw-away suggestion above that the user impact descriptions should go in "the github issue associated with the change" - I guess I want to see some agreement that this is how we're going to go about it. You probably also want to start hassling developers to actually 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 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).

2. Agree to use issues to document user impact statements. Understand that any indication there is a user impact is helpful. Agree it is okay to write a terse impact statement. Agree that mentioning @changelog with no other explanation means you want someone else to write the impact statement. Agree it is okay for someone other than the developer to write impact statements. Agree that if you write @changelog and nobody takes any action, then nobody cares about your change, and that's okay.

3. Create a GitHub openbmc user called "changelog". Then contributors can @mention [102] @changelog in the issue that describes the user impacts,
and all issues that describe user impacts can be found. I had thought to create a new label [8][9] called "User impact" for this purpose, but GitHub permissions do not allow most users to add labels.

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

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

Quoted 17 lines

Andrew

Quoted 15 lines

- 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

#1 lore raw
Quoted 189 lines · Joseph Reynolds
Quoted 161 lines · Andrew Jeffery
Quoted 151 lines · Joseph Reynolds

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 **

How do these changes help connect the folks who contribute to OpenBMC with the folks who use it? The main points are:
1. Contributors write an "end-user impact" statement 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 significant.
3. Release planning summarizes the change log as an input to the release
notes.

Items in detail:

1. Create end-user impact statements.

An "end-user impact" statement summarizes each change from the point of
view of someone familiar with using the external interfaces. It tells them what they need to know about what changed from their point of view,
so they know what to test, how to adapt, etc.

When there is an impact, it should have details like:
- Is there an end-user impact (y/n)?
- Is this a new feature or function (where are the docs)?
- Is this a bug fix?
- What does the end-user need to know (one liner)?
These statements don't have to be perfect. Any inkling you can provide
that there is a user impact is helpful to the community. The impact might change during the release as the design evolves. Different contributors will see different impacts. That's all normal and okay.

Are the following end-user impacts?
- Change to phosphor-webui that affects the browser display? Answer "no" if it doesn't affect usage, or "Yes" if the user will likely notice
or care.
- Bug fix in fan control? Answer 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 the
end-user's use of the external interfaces
- BMCWeb retires old and accepts new TLS encryption algorithms? Yes, it
affects how you can connect to the BMC
- Changes to phosphor-rest or to D-Bus APIs? No, despite their importance, these interfaces are technically internal to the BMC. We might want to document user-impacts to these as well.
- Security fix? Yes, probably, given today's climate
Feel free to come up with your own criteria, based on your estimation of
an end-user.

Writing an "end-user impact" statement bridges two worlds. Folks who work on the code may prefer to leave documentation for others or may not
fully understand the impact of their change on BMC operations. And nobody else may understand the change. So who should write the end-user
impact statement? Anyone who understands the change and how it impacts
end-users. That could be developers, testers, or project managers. Multiple people can contribute over time. And it should be okay to document an end-user impact in someone else's change.

It is important that all of the 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 user impact. (We could use GitHub labels [8][9] to mark issues which have user impact.)

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.

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
merged, minor changes can be omitted, important changes can be 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 use it only to answer specific questions about bugs or features. Only a
few will use it to learn 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 its content. For
example, some groups may use it as part of a software security assurance
process [5].

** Conclusion **

Quoted 8 lines

That's the proposal ... create end-user impact statements ... summarize
them in a change log ... and massage 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.

Quoted 15 lines

So, I think it's a reasonable proposal, however, I think there needs to be
more concrete description of how I as a contributor go about this. There's
a sort-of throw-away suggestion above that the user impact descriptions should go in "the github issue associated with the change" - I guess I want
to see some agreement that this is how we're going to go about it. You probably also want to start hassling developers to actually 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 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).

Quoted 8 lines

2. Agree to use issues to document user impact statements. Understand that any indication there is a user impact is helpful. Agree it is okay to write a terse impact statement. Agree that mentioning @changelog with no other explanation means you want someone else to write the impact statement. Agree it is okay for someone other than the developer to write impact statements. Agree that if you write @changelog and nobody takes any action, then nobody cares about your change, and that's okay.

I have disagreements with this, see below.

Quoted 7 lines

3. Create a GitHub openbmc user called "changelog". Then contributors can @mention [102] @changelog in the issue that describes the user impacts,
and all issues that describe user impacts can be found. I had thought to create a new label [8][9] called "User impact" for this purpose, but GitHub permissions do not allow most users to add labels.

It seems a bit abusive to claim a global name like @changelog for the purpose of the OpenBMC project for what is - essentially - a process hack.

What if other projects wanted to do something similar? Also, anyone on GitHub can mention an account; is there a plan to control "spam" (nice to have a plan for this even if it doesn't eventuate)?

One person is going to have to own the changelog account and go through all its notifications. Who is that one person? Why? Or are we going to do credential sharing? Who are the credentials shared with? On what basis?

Perhaps we need a changelog bot that we can invoke in each issue?

Whatever the case, I think we need to mull over this some more. I don't think the use of an @changelog account is appropriate.

Andrew

#2 lore raw
In reply to Joseph Reynolds

Found it as useful, And from my perspective, not all git-hub issues should have user impact. Because some time  git-hub issue may not be a bug / non recreative / user error too.   I feel only if the issue is a valid one where code changes / design changes happens then git-hub should automatically ask to populate user-impact statement and pull that in release notes automatically.   May be we can request git-hub to check the user impact  field / property is populated for issues where a commit is getting merged.   With regards, Sivas     ----- Original message -----
From: Joseph Reynolds <[email protected]>
Sent by: "openbmc" <[email protected]>
To: Andrew Jeffery <[email protected]>
Cc: [email protected], openbmc <[email protected]>
Subject: Re: [Proposal] End-user impacts and change log + details
Date: Sat, Mar 2, 2019 2:47 AM

Quoted 161 lines · Andrew Jeffery
Quoted 151 lines · Joseph Reynolds

 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 **

 How do these changes help connect the folks who contribute to OpenBMC with the folks who use it?  The main points are:
 1. Contributors write an "end-user impact" statement 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 significant.
 3. Release planning summarizes the change log as an input to the release
 notes.

 Items in detail:

 1. Create end-user impact statements.

 An "end-user impact" statement summarizes each change from the point of
 view of someone familiar with using the external interfaces.  It tells them what they need to know about what changed from their point of view,
 so they know what to test, how to adapt, etc.

 When there is an impact, it should have details like:
 - Is there an end-user impact (y/n)?
 - Is this a new feature or function (where are the docs)?
 - Is this a bug fix?
 - What does the end-user need to know (one liner)?
 These statements don't have to be perfect.  Any inkling you can provide
 that there is a user impact is helpful to the community.  The impact might change during the release as the design evolves.  Different contributors will see different impacts.  That's all normal and okay.

 Are the following end-user impacts?
 - Change to phosphor-webui that affects the browser display?  Answer "no" if it doesn't affect usage, or "Yes" if the user will likely notice
 or care.
 - Bug fix in fan control? Answer 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 the
 end-user's use of the external interfaces
 - BMCWeb retires old and accepts new TLS encryption algorithms?  Yes, it
 affects how you can connect to the BMC
 - Changes to phosphor-rest or to D-Bus APIs?  No, despite their importance, these interfaces are technically internal to the BMC.  We might want to document user-impacts to these as well.
 - Security fix?  Yes, probably, given today's climate
 Feel free to come up with your own criteria, based on your estimation of
 an end-user.

 Writing an "end-user impact" statement bridges two worlds.  Folks who work on the code may prefer to leave documentation for others or may not
 fully understand the impact of their change on BMC operations.  And nobody else may understand the change.  So who should write the end-user
 impact statement?  Anyone who understands the change and how it impacts
 end-users.  That could be developers, testers, or project managers. Multiple people can contribute over time.  And it should be okay to document an end-user impact in someone else's change.

 It is important that all of the 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 user impact. (We could use GitHub labels [8][9] to mark issues which have user impact.)

 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.

 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
 merged, minor changes can be omitted, important changes can be 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 use it only to answer specific questions about bugs or features.  Only a
 few will use it to learn 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 its content. For
 example, some groups may use it as part of a software security assurance
 process [5].

 ** Conclusion **

Quoted 8 lines

 That's the proposal ... create end-user impact statements ... summarize
 them in a change log ... and massage 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.

Quoted 15 lines

 So, I think it's a reasonable proposal, however, I think there needs to be
 more concrete description of how I as a contributor go about this. There's
 a sort-of throw-away suggestion above that the user impact descriptions should go in "the github issue associated with the change" - I guess I want
 to see some agreement that this is how we're going to go about it. You probably also want to start hassling developers to actually 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 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).2. Agree to use issues to document user impact statements.  Understand that any indication there is a user impact is helpful.  Agree it is okay
to write a terse impact statement.  Agree that mentioning @changelog
with no other explanation means you want someone else to write the
impact statement.  Agree it is okay for someone other than the developer
to write impact statements.  Agree that if you write @changelog and
nobody takes any action, then nobody cares about your change, and that's
okay.

3. Create a GitHub openbmc user called "changelog".  Then contributors can @mention [102] @changelog in the issue that describes the user impacts,
and all issues that describe user impacts can be found.  I had thought to create a new label [8][9] called "User impact" for this purpose, but GitHub permissions do not allow most users to add labels.

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

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

Quoted 17 lines

 Andrew

Quoted 15 lines

 - 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

#3 lore raw
In reply to Joseph Reynolds
Quoted 18 lines · Joseph Reynolds
Quoted 17 lines · Andrew Jeffery
Quoted 16 lines · Joseph Reynolds

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].

Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

** 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.

Quoted 24 lines
Quoted 24 lines
Quoted 24 lines

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...

Quoted 9 lines

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...

Quoted 3 lines

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

Quoted 33 lines

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

Quoted 17 lines

Andrew

Quoted 15 lines

- 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