Proposals for commit log policy

[Alexander Amelkin]

Hi Brad, all!

Before I even try to submit any changes directly to CONTRIBUTING.md, I'd like to discuss it here.

What I'm facing is the need to create Release Notes from time to time. Those Release Notes are for server admins, not for openbmc developers. The most difficult and time consuming parts about this effort are:

1. Figuring out the end user impact
2. Figuring out what changes have been brought in by "bump version" commits

Thankfully, for linux-obmc version bumps Patrick Williams and Joel Stanley do a great job by including the 'git shortlog' output. Unfortunately, not everyone is following this rule for bumps. I'd really like this to become a requirement for 'bump version' commits. They could then be parsed automatically. It would also be helpful if  the synopsis included the old and the new hash, e.g.:

=================
some-package: bump version 62286ef3 to 4fa63380

Author Name (2):
  commit 1 synopsis
  another commit synopsis

Another Author (3):
  great commit
  yet another great commit
  fix previous not-so-great commit 

Change-Id: some-long-gerrit-hash
Signed-off-by: The Version Bumper <bumper at nowhere.net>
=================

Including the component's origin git URL could also be helpful for automating change log fetching (finding that in the recipe is sometimes a non-trivial task for a script).

Now for item 1, it would be great if we could have a mandatory "End-user-impact" line/section, like these added to the following real commits:

=================
whitelist: Add new phosphor settings directories
    
The phosphor settings properties used to be stored under
/var/lib/obmc/ but they have moved to /var/lib/phosphor-*
directories.
    
Update the code update whitelist to include these
directories so that the settings properties and inventory
are preserved across code updates.
    
Closes openbmc/openbmc#3346
    
Tested: On Zaius, a PrepareForUpdate and an Apply preserve
the settings.

End-user-impact: None   
Change-Id: I4e528f90128e11af7d40537dceb2f9dd1db6cf73
Signed-off-by: Adriana Kobylak <anoo at us.ibm.com>
=================

or:

=================
Fix to speed up boot to BMC Ready state
   
The legacy services(like system and chassis) was assigned nice value
of 19 to alleviate CPU stress at boot time. The systemd bootchart
showed that many services are dependedent on the system service. The
nice is set to default value of 0 and there is a consistent improvement
of ~10 sec in BMC getting to ready state.

End-user-impact: Speed up BMC booting to Ready state
Change-Id: I8f9f76da0a36c136243026aa7d7691e814634987
Signed-off-by: Tom Joseph <tomjoseph at in.ibm.com>
=================

What do you think? Is this feasible? Any other ideas how we could simplify creating release notes suitable for end users?

I totally understand that for the openbmc project the end users are system vendors, but for them (us) the end users are the server admins, and providing them with usable release notes is crucial. I'm quite sure that this is a kind of task that all vendors face, not just YADRO.

Alexander.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <http://lists.ozlabs.org/pipermail/openbmc/attachments/20180821/741cc9c4/attachment.sig>