1. TSC
  2. Topics

user-facing features recommendations

Luis Gomez
 

Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis



Begin forwarded message:

Subject: Re: [openflowplugin-dev] [integration-dev] [opendaylight.org #7878] Topology broken in Master
From: Luis Gomez <ecelgp@...>
Date: November 7, 2014 at 9:35:22 AM PST
To: "Michal Rehak -X (mirehak - Pantheon Technologies SRO at Cisco)" <mirehak@...>

Hi Michal,

First, thanks for creating the features.

Second, I would suggest to add the essential apps: of-switch-config-pusher, lldl-speaker to odl-openflowplugin-flow-services instead of odl-openflowplugin-all because:

1) Again, if we do not do that we need to ask all projects (not just integration group) consuming odl-openflowplugin-services to add lldl-speaker in their features definition

2) Yesterday we discussed in TSC we should discourage the definition of project-all feature because is creating more confusion than benefit

What I really would like to see from projects this release is the following “ user-facing" features: one or more “essential” features that most users will consume straight away and they are at same level (i.e. one does not build on the other) + zero or more add-on-top features. For example:

odl-openflowplugin-flow-services -> essential feature
odl-openflowplugin-flow-services-rest -> essential + rest
odl-openflowplugin-flow-services-ui -> essential + ui
odl-openflowplugin-flow-services-tme -> essential + table-miss-enforcer

In TSC we still need to articulate and recommend this but in the meantime does it make sense?

BR/Luis



On Nov 7, 2014, at 6:04 AM, Michal Rehak -X (mirehak - Pantheon Technologies SRO at Cisco) <mirehak@...> wrote:

Ok,
I changed features accordingly:
https://git.opendaylight.org/gerrit/#/c/12599/3

Regards,
Michal

From: Anil Vishnoi [vishnoianil@...]
Sent: Friday, November 07, 2014 13:29
To: Michal Rehak -X (mirehak - Pantheon Technologies SRO at Cisco)
Cc: Luis Gomez; 'integration-dev@...' (integration-dev@...) (integration-dev@...); openflowplugin-dev
Subject: Re: [openflowplugin-dev] [integration-dev] [opendaylight.org #7878] Topology broken in Master

I echo the same thoughts as Luis. Keeping all the apps as a separate feature gives more flexibility and freedom to the end user, until and unless these apps are tightly coupled.

Build time is something probably we can live with given that it gives us freedom of creating sophisticate distribution and I feel its more convenient run time solution.

Thanks
Anil

On Fri, Nov 7, 2014 at 5:43 PM, Michal Rehak -X (mirehak - Pantheon Technologies SRO at Cisco)<mirehak@...> wrote:
Hi Luis,
https://git.opendaylight.org/gerrit/12599

There is some description in bugzilla - I decided to have essential apps (lldp-speaker and config-pusher) and one separate app for tableMissEnforcer.

So you can either start all - then ofplugin is supposed to work like before.
Or start all the features one by one and you can add tableMissEnforcer to have some extra flows. 

In case there is a distro requiring special combination of those apps then I think is is fair to let the distro play with features (every feature penalizes build time by 1 minute). But this setup should be suitable for integration.


Regards,
Michal


From: Luis Gomez [ecelgp@...]
Sent: Friday, November 07, 2014 10:30
To: Michal Rehak -X (mirehak - Pantheon Technologies SRO at Cisco)
Cc: Abhijit Kumbhare; 'integration-dev@...' (integration-dev@...) (integration-dev@...); openflowplugin-dev

Subject: Re: [integration-dev] [opendaylight.org #7878] [openflowplugin-dev] Topology broken in Master

Hi Michal,

Any thought on this? at least if you do not plan to include lldl-speaker in odl-openflowplugin-flow-services soon, you should inform other projects to modify their features to include it…

BR/Luis


On Nov 5, 2014, at 2:27 PM, Luis Gomez <ecelgp@...> wrote:

Hi Michal,

Thanks for the explanation. So if you ask me how to proceed here, this is what I would do:

1) Since the 3 apps: table-miss-enforcer, of-switch-config-pusher and lldp-speaker have their own bundle and they have very specific function, I would create a feature for each of them, so you give the user freedom to activate/deactivate what he needs.

2) In addition to that I would put the lldp-speaker feature under odl-openflowplugin-flow-services feature group, this is because most projects consuming this group are expecting topology to work. If a particular user does not want to get lldl-speaker for any reason he can always bring the other features in the odl-openflowplugin-flow-services feature group. IMHO this feature group should contain what most of the openflowplugin consumers will use.

3) The table-miss-enforcer I would leave it as stand-alone feature as it is pushing flows into the network and not everybody likes that

4) The of-switch-config-pusher I would either leave as stand-alone feature (if you do not expect many people to use it) or include it in odl-openflowplugin-flow-services if you think most openflowplugin consumers will use it.

BR/Luis


On Nov 5, 2014, at 1:23 AM, Michal Rehak -X (mirehak - Pantheon Technologies SRO at Cisco) <mirehak@...> wrote:

Hi Luis,
you are right - this is bundle of all apps which were created in ofPlugin. And only lldp-speaker is the one which must be added to integration in order to keep topology working. So probably there should be special feature defined:

<feature name='odl-openflowplugin-apps' description="OpenDaylight :: Openflow Plugin :: Applications" version='${project.version}'>
        <feature version="${project.version}">odl-openflowplugin-flow-services</feature>

      <bundle>mvn:org.opendaylight.openflowplugin.applications/lldp-speaker/${project.version}</bundle>
      <configfile finalname="etc/opendaylight/karaf/71-lldp-speaker.xml">mvn:org.opendaylight.openflowplugin.applications/lldp-speaker/${project.version}/xml/config</configfile>

    <bundle>mvn:org.opendaylight.openflowplugin.applications/of-switch-config-pusher/${project.version}</bundle>
    <configfile finalname="etc/opendaylight/karaf/70-of-switch-config-pusher.xml">mvn:org.opendaylight.openflowplugin.applications/of-switch-config-pusher/${project.version}/xml/config</configfile>
</feature>

 (of course project.version must be changed)

table-miss-enforcer: pushes table miss entry to switch upon connection established (all packetIn will be sent to controller) - this is needed for cpqd and ovs-2.3.0 in order to deliver lldp responses or pings


of-switch-config-pusher: pushed default configuration to switch upon connection established (was previously hardcoded in OFPlugin in handshake code) 
/* Switch configuration. */
struct ofp_switch_config {
    struct ofp_header header;
    uint16_t flags;           /* Bitmap of OFPC_* flags. */
    uint16_t miss_send_len;   /* Max bytes of packet that datapath
                                 should send to the controller. See
                                 ofp_controller_max_len for valid values.
                                 */
};

here we send flags=OFPC_FRAG_NORMAL and miss_send_len=OFPCML_NO_BUFFER.



So in nutshell - only table-miss-enforcer app is kind of new and might break things which rely on empty tables at the beginning. Lldp-speaker and of-switch-config-pusher were there before - just moved to separate module/project.


Question is: 
1) Should we create 2 feature sets, one will contain lldp-speaker and of-switch-config-pusher (default-apps) and the other will contain table-miss-enforcer (extra-apps) so that you can safely set default-apps to be loaded automatically. Those features can be maintained at 1 place.
2) Or should we add only these two apps (lldp-speaker and of-switch-config-pusher) to integration - which would require maintenance for integration features (and some probably by some additional distributions too)?



Regards,
Michal


From: Luis Gomez [ecelgp@...]
Sent: Tuesday, November 04, 2014 22:16
To: Abhijit Kumbhare
Cc: Michal Rehak -X (mirehak - Pantheon Technologies SRO at Cisco); 'integration-dev@...' (integration-dev@...) (integration-dev@...); openflowplugin-dev
Subject: Re: [integration-dev] [opendaylight.org #7878] [openflowplugin-dev] Topology broken in Master

OK, so I tested the odl-openflowplugin-apps feature and topology works. There is also one more thing here, this feature brings the following apps:

mvn:org.opendaylight.openflowplugin.applications/lldp-speaker/0.1.0-SNAPSHOT -> the one we are discussing

mvn:org.opendaylight.openflowplugin.applications/table-miss-enforcer/0.1.0-SNAPSHOT -> this pushes a default flow to send packets to controller, although this is good idea we better check with l2switch project as they are pushing a default flow to discard unknown packets that may interfere with this one

mvn:org.opendaylight.openflowplugin.applications/of-switch-config-pusher/0.1.0-SNAPSHOT -> what is this?

BR/Luis


On Nov 4, 2014, at 11:21 AM, Abhijit Kumbhare <abhijitkoss@...> wrote:

Michal,

I think it will be better to move the LLDP speaker to the OpenFlow plugin project - since it is the only consumer of the LLDP speaker (plus the fact this will break all the projects consuming OpenFlow plugin). What do you think?

Thanks,
Abhijit

On Tue, Nov 4, 2014 at 11:00 AM, Luis Gomez <ecelgp@...> wrote:
Hi Michal,

Thanks for this patch:


I will test it once it gets available to the integration karaf. 

There is one more thing I realized on this change, this is most likely going to break all projects consuming openflowplugin in ODL. And the reason is these projects are pulling odl-openflowplugin-flow-services which does not contain LLDP speaker anymore. So either we send a mail to every project to change their features, or we change in openflowplugin project to include this feature in the odl-openflowplugin-flow-services…

BR/Luis



On Nov 3, 2014, at 6:41 PM, Luis Gomez <ecelgp@...> wrote:

Hi Michal,

On top of this issue I just realized the lldl-speaker bundle is missing from features/pom.xml file. Please address all this issues asap as other projects tests like l2swich or vtn are are currently failing.

BR/Luis


On Nov 3, 2014, at 6:24 PM, Luis Gomez <ecelgp@...> wrote:

I think the problem is in the code itself as it is also failing when I try to install the feature manually:

opendaylight-user@root>feature:install odl-openflowplugin-apps
Error executing command: Error resolving artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT: Could not find artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT in defaultlocal (file:/home/mininet/.m2/repository/)

What I think is happening is the config file for table-miss-enforcer is not being correctly packed in Karaf and so it is trying other maven repos...

BR/Luis


On Nov 3, 2014, at 4:30 PM, Andrew Grimberg via RT <helpdesk@...> wrote:

On Tue, 2014-11-04 at 00:20 +0000, Luis Gomez via RT wrote:

Actually I can see 0.1.0-SNAPSHOT artifact in opendaylight.snapshot:  

https://nexus.opendaylight.org/content/repositories/opendaylight.snapshot/org/opendaylight/openflowplugin/applications/table-miss-enforcer/0.1.0-SNAPSHOT/

but why is pulling the dependency from public
http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
<http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/> repo instead?

We have stated numerous times that since moving into Rackspace there is
an additional Nexus proxy. Even after moving the nexus master into
Rackspace, this proxy is in use. The reason is that it means we don't
have disk contention issues with builds that are uploading and builds
that are acquiring artifacts. The proxy (nexus01.dfw.opendaylight.org)
is an internal only Nexus system. It pulls all ODL related artifacts
from our Nexus master (nexus.opendaylight.org) and all upstream
third-party proxied resources that even our master has to retrieve from
upstream, directly from upstream.

The nexus01 proxy has a TTL of 5 minutes, with a negative TTL of 1
minute. Which means that at worst case an artifact will be 5 minutes
older than what is in our master, and we'll recheck for an artifact that
may have 404ed a maximum of every minute against our master.

The below errors though aren't due to the proxy per-se but to not
actually resolving something correctly. The linked path
( http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
) is the _release_ artifact path and not the SNAPSHOT path, given that a
SNAPSHOT is being requested it's going to fail.

Is the test in question trying to start karaf? We ran into issues with
the integration test controller instance where we had to disable our
forced proxy configuration because starting karaf breaks if it is in
place.

-Andy-

However it fails to build because of:

Tests in error: 
Error resolving artifact
org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT: Could not find artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT in nexus-release-mirror (

http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
)
Error resolving artifact
org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT: Could not find artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT in nexus-release-mirror (

http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
)
Error resolving artifact
org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT: Could not find artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT in nexus-release-mirror (

http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
)
Error resolving artifact
org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT: Could not find artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT in nexus-release-mirror (

http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
)
Error resolving artifact
org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT: Could not find artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT in nexus-release-mirror (

http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
)
Error resolving artifact
org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT: Could not find artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT in nexus-release-mirror (

http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
)
Error resolving artifact
org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT: Could not find artifact org.opendaylight.openflowplugin.applications:table-miss-enforcer:xml:config:0.1.0-SNAPSHOT in nexus-release-mirror (

http://nexus01.dfw.opendaylight.org:8081/nexus/content/groups/public/
)


-- 
Andrew J Grimberg
Systems Administrator
The Linux Foundation

<Mail Attachment>



_______________________________________________
integration-dev mailing list
integration-dev@...
https://lists.opendaylight.org/mailman/listinfo/integration-dev



_______________________________________________
openflowplugin-dev mailing list
openflowplugin-dev@...
https://lists.opendaylight.org/mailman/listinfo/openflowplugin-dev




-- 
Thanks
Anil
Colin Dixon
 

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis
Luis Gomez
 

Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis
Colin Dixon
 

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis
Mathieu Lemay <mlemay@...>
 

Yes that is what blocked me on download page...

On Nov 7, 2014 4:31 PM, "Luis Gomez" <ecelgp@...> wrote:

Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis
Luis Gomez
 

OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis
Colin Dixon
 

So, are you asking:

1.) how projects can tell the TSC (and the rest of the world) which of their features are user-facing once they know internally which features they want to be user facing?

OR

2.) How a project should figure if a feature should be user-facing?

If it's 1, I'd just do it as part of the M3 readout. If it's 2, that's more complicated and really involves asking the question "would a user—not a developer—want to enable and disable this feature?"

--Colin


On Fri, Nov 7, 2014 at 3:48 PM, Luis Gomez <ecelgp@...> wrote:
OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis
Abhijit Kumbhare
 

I think what Luis is asking (or what I think he is asking) makes sense. He wants an intuitive naming convention for the features which is followed by all the projects - so that the users can quickly identify what feature set they should use (base feature set, base feature set with REST, base feature set with REST + UI, etc.). 

On Fri, Nov 7, 2014 at 3:05 PM, Colin Dixon <colin@...> wrote:
So, are you asking:

1.) how projects can tell the TSC (and the rest of the world) which of their features are user-facing once they know internally which features they want to be user facing?

OR

2.) How a project should figure if a feature should be user-facing?

If it's 1, I'd just do it as part of the M3 readout. If it's 2, that's more complicated and really involves asking the question "would a user—not a developer—want to enable and disable this feature?"

--Colin


On Fri, Nov 7, 2014 at 3:48 PM, Luis Gomez <ecelgp@...> wrote:
OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis





_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc
Colin Dixon
 

If that's the question, I would say that the naming convention that openflowplugin and l2switch used was good. We could suggest (or maybe even require it) in Lithium:

1.) <project>-<functionality-name> for the base feature
2.) <project>-<functionality-name>-rest for the base feature with RESTCONF and any other parts needed to make RESTCONF work for the base feature
3.) <project>-<functionality-name>-ui for the base feature with RESTCONF, DLUX, and any other parts needed to make RESTCONF and DLUX work for the base feature

Ideally, we'd have 1 be a subset of 2 and 2 be a subset of 3.

For other options, e.g., the table miss enforcer, I'd ask if they should really be features or options configured via config files, but I'd be open to having that discussion. Keep in mind, the goal is to hit the 90/10 where we provide the ~10% of ways to load features/bundles that will work for 90% of what users want to do. Advanced users can dig in deeper and install exactly the bundles features they want.

If this makes sense, to people we could add them as guidelines in the Karaf Step by Step Guide or even put them as suggestions or requirements in the release plan itself.

--Colin


On Fri, Nov 7, 2014 at 5:33 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I think what Luis is asking (or what I think he is asking) makes sense. He wants an intuitive naming convention for the features which is followed by all the projects - so that the users can quickly identify what feature set they should use (base feature set, base feature set with REST, base feature set with REST + UI, etc.). 

On Fri, Nov 7, 2014 at 3:05 PM, Colin Dixon <colin@...> wrote:
So, are you asking:

1.) how projects can tell the TSC (and the rest of the world) which of their features are user-facing once they know internally which features they want to be user facing?

OR

2.) How a project should figure if a feature should be user-facing?

If it's 1, I'd just do it as part of the M3 readout. If it's 2, that's more complicated and really involves asking the question "would a user—not a developer—want to enable and disable this feature?"

--Colin


On Fri, Nov 7, 2014 at 3:48 PM, Luis Gomez <ecelgp@...> wrote:
OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis





_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc
Abhijit Kumbhare
 

I agree - but probably better to just keep it in the Karaf step-by-step rather than the requirements in the release plan.

On Fri, Nov 7, 2014 at 3:48 PM, Colin Dixon <colin@...> wrote:
If that's the question, I would say that the naming convention that openflowplugin and l2switch used was good. We could suggest (or maybe even require it) in Lithium:

1.) <project>-<functionality-name> for the base feature
2.) <project>-<functionality-name>-rest for the base feature with RESTCONF and any other parts needed to make RESTCONF work for the base feature
3.) <project>-<functionality-name>-ui for the base feature with RESTCONF, DLUX, and any other parts needed to make RESTCONF and DLUX work for the base feature

Ideally, we'd have 1 be a subset of 2 and 2 be a subset of 3.

For other options, e.g., the table miss enforcer, I'd ask if they should really be features or options configured via config files, but I'd be open to having that discussion. Keep in mind, the goal is to hit the 90/10 where we provide the ~10% of ways to load features/bundles that will work for 90% of what users want to do. Advanced users can dig in deeper and install exactly the bundles features they want.

If this makes sense, to people we could add them as guidelines in the Karaf Step by Step Guide or even put them as suggestions or requirements in the release plan itself.

--Colin


On Fri, Nov 7, 2014 at 5:33 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I think what Luis is asking (or what I think he is asking) makes sense. He wants an intuitive naming convention for the features which is followed by all the projects - so that the users can quickly identify what feature set they should use (base feature set, base feature set with REST, base feature set with REST + UI, etc.). 

On Fri, Nov 7, 2014 at 3:05 PM, Colin Dixon <colin@...> wrote:
So, are you asking:

1.) how projects can tell the TSC (and the rest of the world) which of their features are user-facing once they know internally which features they want to be user facing?

OR

2.) How a project should figure if a feature should be user-facing?

If it's 1, I'd just do it as part of the M3 readout. If it's 2, that's more complicated and really involves asking the question "would a user—not a developer—want to enable and disable this feature?"

--Colin


On Fri, Nov 7, 2014 at 3:48 PM, Luis Gomez <ecelgp@...> wrote:
OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis





_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc
Colin Dixon
 

It turns out most of the real documentation was in the karaf features archetype, so I pushed this patch instead of editing the Karaf step-by-step guide:
https://git.opendaylight.org/gerrit/12656

I'll probably also edit the karaf step-by-step guide to put a note there.

--Colin


On Fri, Nov 7, 2014 at 6:02 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I agree - but probably better to just keep it in the Karaf step-by-step rather than the requirements in the release plan.

On Fri, Nov 7, 2014 at 3:48 PM, Colin Dixon <colin@...> wrote:
If that's the question, I would say that the naming convention that openflowplugin and l2switch used was good. We could suggest (or maybe even require it) in Lithium:

1.) <project>-<functionality-name> for the base feature
2.) <project>-<functionality-name>-rest for the base feature with RESTCONF and any other parts needed to make RESTCONF work for the base feature
3.) <project>-<functionality-name>-ui for the base feature with RESTCONF, DLUX, and any other parts needed to make RESTCONF and DLUX work for the base feature

Ideally, we'd have 1 be a subset of 2 and 2 be a subset of 3.

For other options, e.g., the table miss enforcer, I'd ask if they should really be features or options configured via config files, but I'd be open to having that discussion. Keep in mind, the goal is to hit the 90/10 where we provide the ~10% of ways to load features/bundles that will work for 90% of what users want to do. Advanced users can dig in deeper and install exactly the bundles features they want.

If this makes sense, to people we could add them as guidelines in the Karaf Step by Step Guide or even put them as suggestions or requirements in the release plan itself.

--Colin


On Fri, Nov 7, 2014 at 5:33 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I think what Luis is asking (or what I think he is asking) makes sense. He wants an intuitive naming convention for the features which is followed by all the projects - so that the users can quickly identify what feature set they should use (base feature set, base feature set with REST, base feature set with REST + UI, etc.). 

On Fri, Nov 7, 2014 at 3:05 PM, Colin Dixon <colin@...> wrote:
So, are you asking:

1.) how projects can tell the TSC (and the rest of the world) which of their features are user-facing once they know internally which features they want to be user facing?

OR

2.) How a project should figure if a feature should be user-facing?

If it's 1, I'd just do it as part of the M3 readout. If it's 2, that's more complicated and really involves asking the question "would a user—not a developer—want to enable and disable this feature?"

--Colin


On Fri, Nov 7, 2014 at 3:48 PM, Luis Gomez <ecelgp@...> wrote:
OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis





_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc
Luis Gomez
 

Thanks Abhijit, and sorry if I created confusion when I said "define user-facing features" instead of “create karaf user-facing features”. 

My take here is: In general we should let projects define as many features as they want in their repos, but when it comes to "user-facing" features we should recommend a way to create them and probably mandate how to name them.

It is clear to me every project will generate at least 1 base or essential-functionality made of other small features that most users (90/10) will consume via java, REST or GUI so it seems logical to define:

<project>-<essential-functionality> -> for developers 
<project>-<essential-functionality>-rest -> for developers/users
<project>-<essential-functionality>-ui -> for users

Besides that:

1) A project can provide additional essential-functionalities as long as they do not depend on each other, i.e. they are totally independent, then we can treat them the same way:

<project>-<essential-functionality-2> -> for developers 
<project>-<essential-functionality-2>-rest -> for developers/users
<project>-<essential-functionality-2>-ui -> for users


2) A project can also have functionality on top of the essential and this is where I have more questions:

- We can say all functionality over the essential has to be packed within <project>-<essential-functionality> and enabled via configuration

or

- We can be more user friendly and allow individual karaf features for that:

<project>-<essential-functionality>-<extra-functionality-1>
<project>-<essential-functionality>-<extra-functionality-2>

Note that in this case I would not recommend to have -rest -ui in addition but more if a user wants to have both REST and extra functionalities enable:

<project>-<essential-functionality>-rest
<project>-<essential-functionality>-<extra-functionality-1>
<project>-<essential-functionality>-<extra-functionality-2>

for example:

odl-openflow-flow-services-rest
odl-openflow-flow-services-tme <- table miss enforcer
odl-openflow-flow-services-nx <- nx extensions

Also if we allow definition of karaf features for extra functionality, I would not ask projects to document them as separate user-facing features but as extensions (same template) of the essential user-facing feature.

Thoughts?


 

On Nov 7, 2014, at 4:25 PM, Colin Dixon <colin@...> wrote:

It turns out most of the real documentation was in the karaf features archetype, so I pushed this patch instead of editing the Karaf step-by-step guide:
https://git.opendaylight.org/gerrit/12656

I'll probably also edit the karaf step-by-step guide to put a note there.

--Colin


On Fri, Nov 7, 2014 at 6:02 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I agree - but probably better to just keep it in the Karaf step-by-step rather than the requirements in the release plan.

On Fri, Nov 7, 2014 at 3:48 PM, Colin Dixon <colin@...> wrote:
If that's the question, I would say that the naming convention that openflowplugin and l2switch used was good. We could suggest (or maybe even require it) in Lithium:

1.) <project>-<functionality-name> for the base feature
2.) <project>-<functionality-name>-rest for the base feature with RESTCONF and any other parts needed to make RESTCONF work for the base feature
3.) <project>-<functionality-name>-ui for the base feature with RESTCONF, DLUX, and any other parts needed to make RESTCONF and DLUX work for the base feature

Ideally, we'd have 1 be a subset of 2 and 2 be a subset of 3.

For other options, e.g., the table miss enforcer, I'd ask if they should really be features or options configured via config files, but I'd be open to having that discussion. Keep in mind, the goal is to hit the 90/10 where we provide the ~10% of ways to load features/bundles that will work for 90% of what users want to do. Advanced users can dig in deeper and install exactly the bundles features they want.

If this makes sense, to people we could add them as guidelines in the Karaf Step by Step Guide or even put them as suggestions or requirements in the release plan itself.

--Colin


On Fri, Nov 7, 2014 at 5:33 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I think what Luis is asking (or what I think he is asking) makes sense. He wants an intuitive naming convention for the features which is followed by all the projects - so that the users can quickly identify what feature set they should use (base feature set, base feature set with REST, base feature set with REST + UI, etc.). 

On Fri, Nov 7, 2014 at 3:05 PM, Colin Dixon <colin@...> wrote:
So, are you asking:

1.) how projects can tell the TSC (and the rest of the world) which of their features are user-facing once they know internally which features they want to be user facing?

OR

2.) How a project should figure if a feature should be user-facing?

If it's 1, I'd just do it as part of the M3 readout. If it's 2, that's more complicated and really involves asking the question "would a user—not a developer—want to enable and disable this feature?"

--Colin


On Fri, Nov 7, 2014 at 3:48 PM, Luis Gomez <ecelgp@...> wrote:
OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis





_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc
Colin Dixon
 

In general, I think this is right. A few comments inline.

--Colin

On Fri, Nov 7, 2014 at 7:51 PM, Luis Gomez <ecelgp@...> wrote:
Thanks Abhijit, and sorry if I created confusion when I said "define user-facing features" instead of “create karaf user-facing features”. 

My take here is: In general we should let projects define as many features as they want in their repos, but when it comes to "user-facing" features we should recommend a way to create them and probably mandate how to name them.

It is clear to me every project will generate at least 1 base or essential-functionality made of other small features that most users (90/10) will consume via java, REST or GUI so it seems logical to define:

The yangtools, openflowjava, and odlparent projects come to mind as projects that wouldn't have an user-facing features.
 
<project>-<essential-functionality> -> for developers 
<project>-<essential-functionality>-rest -> for developers/users
<project>-<essential-functionality>-ui -> for users

Besides that:

1) A project can provide additional essential-functionalities as long as they do not depend on each other, i.e. they are totally independent, then we can treat them the same way:

<project>-<essential-functionality-2> -> for developers 
<project>-<essential-functionality-2>-rest -> for developers/users
<project>-<essential-functionality-2>-ui -> for users

+1 to this. I wouldn't say they need to be totally independent, but if they are logically separate, it makes a lot of sense. I think the guideline of asking "would a non-developer network operator want to turn this functionality on and off independently of other functionality?" will result in projects making the right choice.

Also, the release plan requires a separate user guide chapter/section per user-facing feature (or intimately related group), which should help projects to think through if it's appropriate or not.
 
2) A project can also have functionality on top of the essential and this is where I have more questions:

- We can say all functionality over the essential has to be packed within <project>-<essential-functionality> and enabled via configuration

or

- We can be more user friendly and allow individual karaf features for that:

<project>-<essential-functionality>-<extra-functionality-1>
<project>-<essential-functionality>-<extra-functionality-2>

Note that in this case I would not recommend to have -rest -ui in addition but more if a user wants to have both REST and extra functionalities enable:

<project>-<essential-functionality>-rest
<project>-<essential-functionality>-<extra-functionality-1>
<project>-<essential-functionality>-<extra-functionality-2>

for example:

odl-openflow-flow-services-rest
odl-openflow-flow-services-tme <- table miss enforcer
odl-openflow-flow-services-nx <- nx extensions

I think this would be fine if projects feel like these extra functionaries are things users would really like to turn on and off regularly and there's not a good default, so a significant fraction of users will want it on and a significant fraction will want it off. Otherwise, I'd encourage it being listed in the developer guide either as a non-user-facing feature or as a configuration option. That's just my thought.
 
Also if we allow definition of karaf features for extra functionality, I would not ask projects to document them as separate user-facing features but as extensions (same template) of the essential user-facing feature.

Thoughts?


 

On Nov 7, 2014, at 4:25 PM, Colin Dixon <colin@...> wrote:

It turns out most of the real documentation was in the karaf features archetype, so I pushed this patch instead of editing the Karaf step-by-step guide:
https://git.opendaylight.org/gerrit/12656

I'll probably also edit the karaf step-by-step guide to put a note there.

--Colin


On Fri, Nov 7, 2014 at 6:02 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I agree - but probably better to just keep it in the Karaf step-by-step rather than the requirements in the release plan.

On Fri, Nov 7, 2014 at 3:48 PM, Colin Dixon <colin@...> wrote:
If that's the question, I would say that the naming convention that openflowplugin and l2switch used was good. We could suggest (or maybe even require it) in Lithium:

1.) <project>-<functionality-name> for the base feature
2.) <project>-<functionality-name>-rest for the base feature with RESTCONF and any other parts needed to make RESTCONF work for the base feature
3.) <project>-<functionality-name>-ui for the base feature with RESTCONF, DLUX, and any other parts needed to make RESTCONF and DLUX work for the base feature

Ideally, we'd have 1 be a subset of 2 and 2 be a subset of 3.

For other options, e.g., the table miss enforcer, I'd ask if they should really be features or options configured via config files, but I'd be open to having that discussion. Keep in mind, the goal is to hit the 90/10 where we provide the ~10% of ways to load features/bundles that will work for 90% of what users want to do. Advanced users can dig in deeper and install exactly the bundles features they want.

If this makes sense, to people we could add them as guidelines in the Karaf Step by Step Guide or even put them as suggestions or requirements in the release plan itself.

--Colin


On Fri, Nov 7, 2014 at 5:33 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I think what Luis is asking (or what I think he is asking) makes sense. He wants an intuitive naming convention for the features which is followed by all the projects - so that the users can quickly identify what feature set they should use (base feature set, base feature set with REST, base feature set with REST + UI, etc.). 

On Fri, Nov 7, 2014 at 3:05 PM, Colin Dixon <colin@...> wrote:
So, are you asking:

1.) how projects can tell the TSC (and the rest of the world) which of their features are user-facing once they know internally which features they want to be user facing?

OR

2.) How a project should figure if a feature should be user-facing?

If it's 1, I'd just do it as part of the M3 readout. If it's 2, that's more complicated and really involves asking the question "would a user—not a developer—want to enable and disable this feature?"

--Colin


On Fri, Nov 7, 2014 at 3:48 PM, Luis Gomez <ecelgp@...> wrote:
OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it.

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis





_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc
Luis Gomez
 

I agree on all comments (see below). What would be the best way to post this information? new wiki, existing wiki, feature archetype?

BR/Luis


On Nov 8, 2014, at 1:02 PM, Colin Dixon <colin@...> wrote:

In general, I think this is right. A few comments inline.

--Colin

On Fri, Nov 7, 2014 at 7:51 PM, Luis Gomez <ecelgp@...> wrote:
Thanks Abhijit, and sorry if I created confusion when I said "define user-facing features" instead of “create karaf user-facing features”. 

My take here is: In general we should let projects define as many features as they want in their repos, but when it comes to "user-facing" features we should recommend a way to create them and probably mandate how to name them.

It is clear to me every project will generate at least 1 base or essential-functionality made of other small features that most users (90/10) will consume via java, REST or GUI so it seems logical to define:

The yangtools, openflowjava, and odlparent projects come to mind as projects that wouldn't have an user-facing features.

You are right, I forgot about these projects ;)

 
<project>-<essential-functionality> -> for developers 
<project>-<essential-functionality>-rest -> for developers/users
<project>-<essential-functionality>-ui -> for users

Besides that:

1) A project can provide additional essential-functionalities as long as they do not depend on each other, i.e. they are totally independent, then we can treat them the same way:

<project>-<essential-functionality-2> -> for developers 
<project>-<essential-functionality-2>-rest -> for developers/users
<project>-<essential-functionality-2>-ui -> for users

+1 to this. I wouldn't say they need to be totally independent, but if they are logically separate, it makes a lot of sense. I think the guideline of asking "would a non-developer network operator want to turn this functionality on and off independently of other functionality?" will result in projects making the right choice.

Agree


Also, the release plan requires a separate user guide chapter/section per user-facing feature (or intimately related group), which should help projects to think through if it's appropriate or not.
 
2) A project can also have functionality on top of the essential and this is where I have more questions:

- We can say all functionality over the essential has to be packed within <project>-<essential-functionality> and enabled via configuration

or

- We can be more user friendly and allow individual karaf features for that:

<project>-<essential-functionality>-<extra-functionality-1>
<project>-<essential-functionality>-<extra-functionality-2>

Note that in this case I would not recommend to have -rest -ui in addition but more if a user wants to have both REST and extra functionalities enable:

<project>-<essential-functionality>-rest
<project>-<essential-functionality>-<extra-functionality-1>
<project>-<essential-functionality>-<extra-functionality-2>

for example:

odl-openflow-flow-services-rest
odl-openflow-flow-services-tme <- table miss enforcer
odl-openflow-flow-services-nx <- nx extensions

I think this would be fine if projects feel like these extra functionaries are things users would really like to turn on and off regularly and there's not a good default, so a significant fraction of users will want it on and a significant fraction will want it off. Otherwise, I'd encourage it being listed in the developer guide either as a non-user-facing feature or as a configuration option. That's just my thought.

Yes, it seems reasonable

 
Also if we allow definition of karaf features for extra functionality, I would not ask projects to document them as separate user-facing features but as extensions (same template) of the essential user-facing feature.

Thoughts?


 

On Nov 7, 2014, at 4:25 PM, Colin Dixon <colin@...> wrote:

It turns out most of the real documentation was in the karaf features archetype, so I pushed this patch instead of editing the Karaf step-by-step guide:
https://git.opendaylight.org/gerrit/12656

I'll probably also edit the karaf step-by-step guide to put a note there.

--Colin


On Fri, Nov 7, 2014 at 6:02 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I agree - but probably better to just keep it in the Karaf step-by-step rather than the requirements in the release plan.

On Fri, Nov 7, 2014 at 3:48 PM, Colin Dixon <colin@...> wrote:
If that's the question, I would say that the naming convention that openflowplugin and l2switch used was good. We could suggest (or maybe even require it) in Lithium:

1.) <project>-<functionality-name> for the base feature
2.) <project>-<functionality-name>-rest for the base feature with RESTCONF and any other parts needed to make RESTCONF work for the base feature
3.) <project>-<functionality-name>-ui for the base feature with RESTCONF, DLUX, and any other parts needed to make RESTCONF and DLUX work for the base feature

Ideally, we'd have 1 be a subset of 2 and 2 be a subset of 3.

For other options, e.g., the table miss enforcer, I'd ask if they should really be features or options configured via config files, but I'd be open to having that discussion. Keep in mind, the goal is to hit the 90/10 where we provide the ~10% of ways to load features/bundles that will work for 90% of what users want to do. Advanced users can dig in deeper and install exactly the bundles features they want.

If this makes sense, to people we could add them as guidelines in the Karaf Step by Step Guide or even put them as suggestions or requirements in the release plan itself.

--Colin


On Fri, Nov 7, 2014 at 5:33 PM, Abhijit Kumbhare <abhijitkoss@...> wrote:
I think what Luis is asking (or what I think he is asking) makes sense. He wants an intuitive naming convention for the features which is followed by all the projects - so that the users can quickly identify what feature set they should use (base feature set, base feature set with REST, base feature set with REST + UI, etc.). 

On Fri, Nov 7, 2014 at 3:05 PM, Colin Dixon <colin@...> wrote:
So, are you asking:

1.) how projects can tell the TSC (and the rest of the world) which of their features are user-facing once they know internally which features they want to be user facing?

OR

2.) How a project should figure if a feature should be user-facing?

If it's 1, I'd just do it as part of the M3 readout. If it's 2, that's more complicated and really involves asking the question "would a user—not a developer—want to enable and disable this feature?"

--Colin


On Fri, Nov 7, 2014 at 3:48 PM, Luis Gomez <ecelgp@...> wrote:
OK, I think I am not explaining myself clear. The problem is not documenting an already defined feature, the problem is to come up with a standard model for projects to identify user-facing features. Do we have already a wiki where we explain what a user-facing feature is and how to identify them with some examples? this is what i am really looking for...

BR/Luis



On Nov 7, 2014, at 1:39 PM, Colin Dixon <colin@...> wrote:

The documentation requirements for Lithium [0] try to take a stab at this when they say:
"Intimately related features, e.g., l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui, can be documented as one noting the differences"

In the example you have, I'd imagine that covers pretty much everything if you explain which exact feature to install when and then document them together as one logical entity (which they are).

Does that make sense?

Cheers,
--Colin

On Fri, Nov 7, 2014 at 3:31 PM, Luis Gomez <ecelgp@...> wrote:
Hi Colin,

My point is user-facing features are key yes but their definition is not as simple as it seems, it can be done in very many different ways (see the discussion with ofplugin project I sent earlier) and we do not want to end up with a totally disparate set of user-facing features coming from the different projects (at least I would not like). 

BR/Luis


On Nov 7, 2014, at 10:27 AM, Colin Dixon <colin@...> wrote:

We do really need to have a list of user-facing features (if any) from each project. I can add that to part of features definition in the main release plan if everyone agrees that makes sense.

We need this designation to inform what kinds of user documentation projects should generate and also to inform the installation guide as well as any automated installer/downloader/configurator we want to provide.

My gut reaction is that we just want a list of these features (possibly with options, e.g., to say that l2switch-switch, l2switch-switch-rest, and l2switch-switch-ui are "the same" feature with different options) from projects in a human-readable format and if we develop a machine parseable version with tooling, we can encourage projects to use it. 

--Colin

On Fri, Nov 7, 2014 at 12:03 PM, Luis Gomez <ecelgp@...> wrote:
Dear TSC,

Yesterday call and this conversation with ofplugin project today remind me this release we should define and make some recommendations to projects on how to define their “user-facing” features. Do you agree? if so any volunteers to start working on this?

BR/Luis





_______________________________________________
TSC mailing list
TSC@...
https://lists.opendaylight.org/mailman/listinfo/tsc

1 - 14 of 14