REST API docs

[Benjamin Herrenschmidt]

On Thu, 2017-08-03 at 01:13 -0500, Patrick Williams wrote:
> > You cannot change an API in a backward compatible way and keep the doc
> > documenting the old/wrong way in the repo. That's just plain wrong.
> > 
> > Ben.
> > 
> 
> Fair enough.  I honestly though calling this entire code stream 1.99.x
> was sufficient "hear be dragons" to prevent people from coding to things
> unless they speak up.  

Haha, yeah well ... I think you should at least delete the docs or move
them to a "deprecated" directory or something when you break what they
document.

It's understandable that you may not have the bandwidth to update all
the docs right away (though in OPAL at least we tend to push for
requiring docs in the commit with with the feature change these days),
but it would help to make it clear that those docs aren't to be
trusted.

> We've been actively engaging the teams that we
> knew were affected by all of our API changes, and we were not aware of
> this one.  The teams we keep informed outside of the direct development
> community are: openbmc test-automation team, xCAT, and the GUI
> development team.

Engaging with team is great but you can't always know everybody who's
looking at or playing with your stuff.

> I will make sure we go through the docs repository soon and clearly point
> out everything that is deprecated in the 1.99.x code stream as such.

Yup, or at least move the whole thing to a "deprecated-needs-update"
directory until you had a chance to do the filtering. Maybe a toplevel
"WARNING" file with a one-liner about the domain change.

Cheers,
Ben.