[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[Pulp-list] About release notes



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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]