On the state of documentation

[Brad Bishop]

> On Nov 16, 2017, at 10:03 PM, Stewart Smith <stewart at linux.vnet.ibm.com> wrote:
> 
> "Tanous, Ed" <ed.tanous at intel.com> writes:
>> I believe that the lack of good documentation is a symptom of a larger
>> issue:  OpenBMC is not targeting a public specification with its REST
>> interface.  This has led to certain engineering flexibilities with the
>> interface that, while useful for short term to "get something that
>> works", make it very difficult to target openbmc an evolving platform.
>> In the current model, DBus specifications are pushed directly to the
>> end user, which means (nearly) every DBus spec change results in a
>> change to end user interfaces.  I don't believe this is sustainable in
>> the long run, given the number of platforms that this is targeting and
>> the need for reproducible APIs between systems.

No disagreement here.  The project could really could use a Redfish
and full IPMI implementation.

> 
> I very much agree.
> 
> As someone consuming it, for the purposes of automating testing host
> firmware (for the purpose of being a host firmware maintainer), it's
> been *extroadinarily* frustrating. Upgrading a BMC usually meant 0.5-1
> day of working out what API change broke and how to code something that
> was safe for more than one OpenBMC build.
> 
> Additionally, much of the docs of the DBUS API are currently written
> targetting somebody working on OpenBMC internals.
> 
>> I would argue

Argue implies disagreement?  I completely agree we need a Redfish
implementation.  Have you heard something that suggests there would
be push back on someone implementing Redfish?

>> that middle to long term we should transition away from
>> these interfaces for end-user facing functionality, and move toward

Words like 'transition away' and 'move toward' are kind of freaking me out
a little.  Are you suggesting that OpenBMC can _only_ have a Redfish
implementation?  Any other REST API implementation would be…banned from
the project?  Or am I reading into it too much?

>> something that has a standard behind it.  I think the obvious choice
>> in this problem space is redfish, but I'm open to other options.
> 
> I am 100% with you on that.
> 
> RedFish may not be ideal (neither is IPMI), but it's *standard*, so at
> least it's not just a OpenBMC problem.
> 
> I see at least 2 other BMCs I have to deal with going the RedFish route,
> so I'd honestly like to see OpenBMC go there.
> 
> I view all the code I've written against the OpenBMC REST API to be
> throw-away code... but that's what I've been told by the IBM team they
> support, so there hasn't really been a choice apart from rewriting half
> of it every month for no discernable good reason.
> 
>> I'd like to pose the question:
>> Should we move toward deprecating the /xyz and /org style rest
>> interfaces, and agree that we should start transitioning to something
>> (redfish or not) with a fixed specification?
> 
> My vote is YES, *PLEASE* YES.

Like I said, I too agree we need a Redfish and IPMI implementation
in OpenBMC.

That said, what reason is there to get rid of the existing DBus<->REST
translation server?  It’s not as if its a maintenance burden.  It isn’t
as if anyone is making people use it in their products.  Its there.
You can use it or not use it.  When we have an IPMI or Redfish
implementation, I’ll be the first in line (well maybe second after
Stewart) to tell my employer to turn it off in their products.
That isn’t the same thing as removing it from the project altogether.

> 
>> Some important key points that I think should be driven by the new model:
>> 1. Rest interfaces should not be driven by the underlying DBus interfaces, nor the backend implementation language.

This reads like policy for someone using OpenBMC to build a BMC stack.

I would rephrase it to:

XYZ corp cannot use any REST implementations provided by OpenBMC that are
driven by the underlying DBus interfaces in XYZ corp products making use
of OpenBMC.

Do you see the difference?

>> 2. Interfaces should not contain any "backdoor" type APIs that allow white box style access to internal APIs.  Anything breaking the black box model should be done in a machine specific layer or configuration.
>> 3. APIs should give the minimum required amount of information to fulfill the end user use case.
>> 4. Interfaces should be backed by the system level security policy (PAM users in the current model).
>> 5. Where possible, the implementations should follow an existing specification.  In the cases where the requirements are not supported, the api should follow the style of the supporting interface  (Think redfish OEM command support)

I have the same reaction to 2-6 as I did for 1.  These are policies on _use_
of OpenBMC.  Right?  Not what the contributors to the project are allowed to do.

My worldview is that each one of these bullet points would cost the project a
potential contributor.  Somewhere, someone is going to want to do one of
those things.  Why not let them, when the only thing you have to do is not use
their code?

>> 6. Documentation changes should be pushed ahead of or along with
>> implementation support, with the goal of keeping the documentation
>> constantly up to date.

On point #6 I agree completely.

> 
> Completely agree.
>> Shameless plug: As the person that pushed the aforementioned gerrit
>> review for a new thinking on the webserver and redfish, I would love
>> comments on architecture decisions and implementation details.
> 
> I nearly commented MERGE NOW without even looking, but that's possibly a
> bit keen :)
> 
> I reckon the Minimum Viable Product for something is enough to do what
> TripleO needs (which is probably the same set of things that I need for
> OPAL testing). Once it's there, I say go for it - internals can be
> cleaned up, but at least those of us consuming OpenBMC have a good way
> forward along with an upstream spec to point to and look at.
> 
> -- 
> Stewart Smith
> OPAL Architect, IBM.


thx - brad