Opinions on CLI tools.

Opinions on CLI tools.

[Patrick Williams]

[-- Attachment #1: Type: text/plain, Size: 2445 bytes --]

I decided we should solicit broader feedback before I merge this commit:
    https://gerrit.openbmc-project.xyz/#/c/900/2

Xo proposed adding a CLI tool, that appears to have been written and
maintained by someone at Google, and effectively is a wrapper around a
number of device driver calls.  Some of the facilities provided by this
tool would also be provided by "upstream" tools like i2c-tools or pdbg.

Last week the IBM team had a small discussion on strategies for CLI
tools.  In our legacy product, developers tended to make many many CLI
tools with little oversight and standards and these tools ended up
slipping into various "bring up", "debug" and "manufacturing" scripts,
effectively becoming "requirements".  For OpenBMC, we had proposed
landing on the other extreme of this, which is to say we should never
have a CLI tool as a wrapper around an existing tool or to replace
existing upstream functionality.  (We did have one small tool we
discussed which was to facilitate easier interaction with the DBus
interfaces, since otherwise would require a few invocations of 'busctl')

One of our (my) concerns about wrappers is that we end up segmenting our
own community from the broader Linux ecosystem.  Having available and
documenting broader tools like 'i2c-tools', 'systemctl', 'journalctl'
gives us larger mind-share with individuals outside OpenBMC that are
already familiar with those tools.

A key example we discussed was:
        obmcutil power-on
    vs
        systemctl start host0-power-on.target

The first is certainly "easier" for those that are totally newcomers.
The second is only slightly more difficult but gives insight into how
our state-management works.  With the second if someone already has
knowledge in systemd, from their own Linux experience, that allows them
to more likely probe into "what else is exposed via systemd targets?"
rather than just expecting everything to be documented with 'obmcutil
--help'.

With this proposed iotools package I think we have 3 options:

1.  Allow it in, as is, in the debugtools image.  Even though it does
replicate / wrap some tools, it does provide new abstractions on others.

2.  Add it to a .bbappend in only the meta-zaius tree.

3.  Patch the makefile (and discuss with upstream) to disable
functionality that is already implemented by other, more widely used,
tools like i2c-tools.

-- 
Patrick Williams

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: Opinions on CLI tools.

[Brad Bishop]

If there is value add in these tools, lets get those enhancements in the
associated upstream projects.  I agree with the segmentation and mind-share
kool-aid.

That said, the beauty of Yocto is layers, and if someone felt strongly about it,
this could be added as-is to a meta-<machine> or meta-<company> layer.  Then
the segmentation and mindshare loss would at least be confined to that particular
layer.

-brad


> On Oct 31, 2016, at 11:00 AM, Patrick Williams <patrick@stwcx.xyz> wrote:
> 
> I decided we should solicit broader feedback before I merge this commit:
>    https://gerrit.openbmc-project.xyz/#/c/900/2
> 
> Xo proposed adding a CLI tool, that appears to have been written and
> maintained by someone at Google, and effectively is a wrapper around a
> number of device driver calls.  Some of the facilities provided by this
> tool would also be provided by "upstream" tools like i2c-tools or pdbg.
> 
> Last week the IBM team had a small discussion on strategies for CLI
> tools.  In our legacy product, developers tended to make many many CLI
> tools with little oversight and standards and these tools ended up
> slipping into various "bring up", "debug" and "manufacturing" scripts,
> effectively becoming "requirements".  For OpenBMC, we had proposed
> landing on the other extreme of this, which is to say we should never
> have a CLI tool as a wrapper around an existing tool or to replace
> existing upstream functionality.  (We did have one small tool we
> discussed which was to facilitate easier interaction with the DBus
> interfaces, since otherwise would require a few invocations of 'busctl')
> 
> One of our (my) concerns about wrappers is that we end up segmenting our
> own community from the broader Linux ecosystem.  Having available and
> documenting broader tools like 'i2c-tools', 'systemctl', 'journalctl'
> gives us larger mind-share with individuals outside OpenBMC that are
> already familiar with those tools.
> 
> A key example we discussed was:
>        obmcutil power-on
>    vs
>        systemctl start host0-power-on.target
> 
> The first is certainly "easier" for those that are totally newcomers.
> The second is only slightly more difficult but gives insight into how
> our state-management works.  With the second if someone already has
> knowledge in systemd, from their own Linux experience, that allows them
> to more likely probe into "what else is exposed via systemd targets?"
> rather than just expecting everything to be documented with 'obmcutil
> --help'.
> 
> With this proposed iotools package I think we have 3 options:
> 
> 1.  Allow it in, as is, in the debugtools image.  Even though it does
> replicate / wrap some tools, it does provide new abstractions on others.
> 
> 2.  Add it to a .bbappend in only the meta-zaius tree.
> 
> 3.  Patch the makefile (and discuss with upstream) to disable
> functionality that is already implemented by other, more widely used,
> tools like i2c-tools.
> 
> -- 
> Patrick Williams
> _______________________________________________
> openbmc mailing list
> openbmc@lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/openbmc

Re: Opinions on CLI tools.

[Xo Wang]

Hi Patrick, Brad:

Based on your criteria, I think iotools would fall into the category
of a narrow-mindshare tool when viewed from the broader project
perspective.

We'll keep the iotools image inclusion internal to our layer, since
the primary benefit is Google developer familiarity and ease of
porting our collection of traditionally host-side scripts that depend
on it.

cheers
xo


On Tue, Nov 1, 2016 at 6:30 AM, Brad Bishop <bradleyb@fuzziesquirrel.com> wrote:
> If there is value add in these tools, lets get those enhancements in the
> associated upstream projects.  I agree with the segmentation and mind-share
> kool-aid.
>
> That said, the beauty of Yocto is layers, and if someone felt strongly about it,
> this could be added as-is to a meta-<machine> or meta-<company> layer.  Then
> the segmentation and mindshare loss would at least be confined to that particular
> layer.
>
> -brad
>
>
>> On Oct 31, 2016, at 11:00 AM, Patrick Williams <patrick@stwcx.xyz> wrote:
>>
>> I decided we should solicit broader feedback before I merge this commit:
>>    https://gerrit.openbmc-project.xyz/#/c/900/2
>>
>> Xo proposed adding a CLI tool, that appears to have been written and
>> maintained by someone at Google, and effectively is a wrapper around a
>> number of device driver calls.  Some of the facilities provided by this
>> tool would also be provided by "upstream" tools like i2c-tools or pdbg.
>>
>> Last week the IBM team had a small discussion on strategies for CLI
>> tools.  In our legacy product, developers tended to make many many CLI
>> tools with little oversight and standards and these tools ended up
>> slipping into various "bring up", "debug" and "manufacturing" scripts,
>> effectively becoming "requirements".  For OpenBMC, we had proposed
>> landing on the other extreme of this, which is to say we should never
>> have a CLI tool as a wrapper around an existing tool or to replace
>> existing upstream functionality.  (We did have one small tool we
>> discussed which was to facilitate easier interaction with the DBus
>> interfaces, since otherwise would require a few invocations of 'busctl')
>>
>> One of our (my) concerns about wrappers is that we end up segmenting our
>> own community from the broader Linux ecosystem.  Having available and
>> documenting broader tools like 'i2c-tools', 'systemctl', 'journalctl'
>> gives us larger mind-share with individuals outside OpenBMC that are
>> already familiar with those tools.
>>
>> A key example we discussed was:
>>        obmcutil power-on
>>    vs
>>        systemctl start host0-power-on.target
>>
>> The first is certainly "easier" for those that are totally newcomers.
>> The second is only slightly more difficult but gives insight into how
>> our state-management works.  With the second if someone already has
>> knowledge in systemd, from their own Linux experience, that allows them
>> to more likely probe into "what else is exposed via systemd targets?"
>> rather than just expecting everything to be documented with 'obmcutil
>> --help'.
>>
>> With this proposed iotools package I think we have 3 options:
>>
>> 1.  Allow it in, as is, in the debugtools image.  Even though it does
>> replicate / wrap some tools, it does provide new abstractions on others.
>>
>> 2.  Add it to a .bbappend in only the meta-zaius tree.
>>
>> 3.  Patch the makefile (and discuss with upstream) to disable
>> functionality that is already implemented by other, more widely used,
>> tools like i2c-tools.
>>
>> --
>> Patrick Williams
>> _______________________________________________
>> openbmc mailing list
>> openbmc@lists.ozlabs.org
>> https://lists.ozlabs.org/listinfo/openbmc
> _______________________________________________
> openbmc mailing list
> openbmc@lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/openbmc

Re: Opinions on CLI tools.

[Joel Stanley]

On Wed, Nov 2, 2016 at 8:41 AM, Xo Wang <xow@google.com> wrote:
> Hi Patrick, Brad:
>
> Based on your criteria, I think iotools would fall into the category
> of a narrow-mindshare tool when viewed from the broader project
> perspective.
>
> We'll keep the iotools image inclusion internal to our layer, since
> the primary benefit is Google developer familiarity and ease of
> porting our collection of traditionally host-side scripts that depend
> on it.

Out of interest, which of the tools in there are you using?

Cheers,

Joel

Re: Opinions on CLI tools.

[Andrew Geissler]

I still feel like we're doing a lot of "developer-biased" decision
making here.  We're going to have people in the lab and other general
users of obmc that shouldn't have to understand the details of our
implementation of things like service states and such.

As a general user of a system with an obmc, I want to simply know "Is
everything running as expected"  "Is the system in a state where it
can perform it's intended function"
And also, I want a simple command to "put it in the state where it can
do it's intended function".

This to me is a lot like all of our software design principles,
abstract the details away!  I don't care how the stl implements a
vector, I just want a vector.  If I'm writing the stl implementation
then obviously I care about it's details.

But, the above was definitely not the consensus last week in the
workshop.  I know what will happen, at least in the lab here in IBM,
people will write their own wrappers, they'll put them in shared
locations for others to use, and we'll then start getting issues
opened against us with people using those wrappers.

Luckily, this is a fairly easy issue to solve it becomes a problem (as
I predict), so starting with a design where we do nothing is not the
worst decision :)

Andrew

On Tue, Nov 1, 2016 at 6:50 PM, Joel Stanley <joel@jms.id.au> wrote:
> On Wed, Nov 2, 2016 at 8:41 AM, Xo Wang <xow@google.com> wrote:
>> Hi Patrick, Brad:
>>
>> Based on your criteria, I think iotools would fall into the category
>> of a narrow-mindshare tool when viewed from the broader project
>> perspective.
>>
>> We'll keep the iotools image inclusion internal to our layer, since
>> the primary benefit is Google developer familiarity and ease of
>> porting our collection of traditionally host-side scripts that depend
>> on it.
>
> Out of interest, which of the tools in there are you using?
>
> Cheers,
>
> Joel
> _______________________________________________
> openbmc mailing list
> openbmc@lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/openbmc

Re: Opinions on CLI tools.

[Patrick Williams]

[-- Attachment #1: Type: text/plain, Size: 1528 bytes --]

On Thu, Nov 03, 2016 at 09:00:28AM -0500, Andrew Geissler wrote:
> I still feel like we're doing a lot of "developer-biased" decision
> making here.  We're going to have people in the lab and other general
> users of obmc that shouldn't have to understand the details of our
> implementation of things like service states and such.

I don't think this is "developer-biased" as much as you are implying it
is.  There are two kinds of people...

    1) Person who has some familiarity with existing open source tools.
    2) Person who has no familiar with existing open source tools.

For person #1, if we document power-on is "systemctl start
host-power-on@1.target" they have learned something about our system and
they might be able to learn more on their own through exploration.  If
we document power-on is "obmcutil power-on" we have taught them nothing.

For person #2, if we document power-on is "systemctl start
host-power-on@1.target" they will copy and paste it into a terminal.  If
we document power-on is "obmcutil power-on" they will copy and paste it
into a terminal.

We haven't lost anything by not providing "obmcutil power-on" except 15
extra characters.  We have lost something by providing (and documenting)
"obmcutil power-on".

You use the term "developer-biased" but it is really "general Linux
knowledge" biased.  Person #2 doesn't have it and probably never will;
they are going to be a "copy and paste" user their whole life so why
cater to them?

-- 
Patrick Williams

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 801 bytes --]