[Pulp-list] About release notes

[Jay Dobies]

One of the main purposes of release notes is to build hype and excite 
the user to upgrade. We're good at that part. The other purpose is to 
not totally piss off the user when they upgrade. That part we need a bit 
of work on. Since the CR19 release notes are fresh in my head, I wanted 
to throw a few suggestions out there of things that fall into this category:


= Pulp-Built Dependencies =
This is something I never thought to include until this release. Our 
repos have a few libraries that we patched and built. The Pulp 
install/upgrade process will pick these up as newer versions than what 
users may have installed and upgrade them.

We really should warn people when a CR contains a new version of these 
dependencies. They may be using the libraries for other reasons (or 
their own patched versions of them) and our version overwriting that may 
be bad. Arguably, users should look at the list of dependencies on 
install, but it's good mojo if we warn them in the release notes.


= API Changes =
The longer Pulp is around the more this becomes important. We're having 
more and more people using our APIs, so we really need to raise a giant 
red flag in the release notes telling them which APIs have changed so 
they have an idea if the upgrade will break their usage of us. (Let's 
just skip the backward compatibility argument that's gonna be the snap 
reaction to this, it's a beast in and of itself).


= CLI Changes =
Pretty much the same rationale as above. Users (and our own QE 
department) may have scripted pulp-admin and pulp-client commands that 
may be affected if we go and change up commands and arguments. We should 
warn them ahead of time that these things have changed. (Again, we can 
talk about backward compatibility separately).


= Pulp Migrate One-Offs =
We've been good about this, but listing it for completeness. If there is 
something in the database that pulp-migrate can't handle, or some sort 
of warning about data that will change in the future that requires 
manual intervention, we need to highlight this so users know.


There might be more, but as a starting point please keep these in mind 
when delivering your release notes to me so I can highlight them 
appropriately.

-- 
Jay Dobies
Freenode: jdob @ #pulp
http://pulpproject.org | http://blog.pulpproject.org