Ton, It seems the approach you proposed requires the yaml file that describes all the labels to be copied between repos (openstack/magnum, openstack/python-magnumclient, openstack/magnum-ui). Unless we setup a CI job to copy the file, I don't think it can solve the maintenance problem.
Best regards, Hongbin On Thu, May 12, 2016 at 4:33 PM, Ton Ngo <t...@us.ibm.com> wrote: > I would like to add some context for a bigger picture so we might arrive > at a more general solution. > Typically CLI options are fairly static so the help messages are usually > coded directly in the client. > This provides a good user experience by making the info readily available > to the users. > The case for label is a little different, because label provides a general > mechanism to pass arbitrary key/value pairs. > The meaning for these key/value is interpreted based on a particular > option in a particular COE type, so they are not generally applicable. > For instance, Kubernetes baymodel that uses flannel as network-driver > supports the label "flannel_backend", with the allowed values of "udp, > vxlan, host-gw". > This particular label would be meaningless in another COE like Mesos. > > So to provide this kind of info to the users, we have to address 2 issues: > > 1. How the user can discover the available labels specific to the COE, > along with the valid values to specify. > 2. How to maintain the help messages specific to each label since they > are likely to change frequently. > > > I think just displaying the info for all labels together would not be too > helpful. > Putting the info in the API would make it available to tools built on > Magnum, but Madhuri has a good point that the info would not be available > when the server is not running. > We need to accommodate new bay drivers that may add new labels. > Validation for the label value is another requirement. > > Here is a thought on how to meet these requirements: we can install a yaml > file in /etc/magnum/labels.yaml that would describe all the supported > labels, something like: > > flannel_backend: > valid_values: > -udp > -vxlan > -host-gw > default_value: udp > COE: > -kubernetes > -swarm > help_message: "This label is used with the flannel network driver to > specify the type of back end to use. The option host-gw gives the best > bandwidth performance." > doc_url: "http://xxx"; > > Then the client can read this yaml file and list the labels for a COE, say > Kubernetes. For help on a specific label, the client would print the help > message along with the url for further info (if available) > The validation code can also load this file for a more general way to > validate the baymodel, avoiding hardcoding in api/attr_validator.py > New bay drivers can just append new labels to this file to have them > handled in the same way as Magnum supported labels. > Optionally, the API server can provide access to this info. > In the source, we can keep this file in etc/magnum/labels.yaml. > Maintaining the help messages would be simpler since we just need to edit > the file. > > Thought? > > Ton, > > > [image: Inactive hide details for Jamie Hannaford ---05/12/2016 07:08:47 > AM---+1 for 1 and 3. I'm not sure maintainability should disco]Jamie > Hannaford ---05/12/2016 07:08:47 AM---+1 for 1 and 3. I'm not sure > maintainability should discourage us from exposing information to the u > > From: Jamie Hannaford <jamie.hannaf...@rackspace.com> > To: "OpenStack Development Mailing List (not for usage questions)" < > openstack-dev@lists.openstack.org> > Cc: Qun XK Wang <bjw...@cn.ibm.com> > Date: 05/12/2016 07:08 AM > Subject: Re: [openstack-dev] [magnum] How to document 'labels' > ------------------------------ > > > > +1 for 1 and 3. > > I'm not sure maintainability should discourage us from exposing > information to the user through the client - we'll face the same > maintenance burden as we currently do, and IMO it's our job as a team to > ensure our docs are up-to-date. Any kind of input which touches the API > should also live in the API docs, because that's in line with every other > OpenStack service. > > I don't think I've seen documentation exposed via the API before (#2). I > think it's a lot of work too, and I don't see what benefit it provides. > > Jamie > > ------------------------------ > > *From:* Hongbin Lu <hongbin...@huawei.com> > *Sent:* 11 May 2016 21:52 > *To:* OpenStack Development Mailing List (not for usage questions) > *Cc:* Qun XK Wang > *Subject:* [openstack-dev] [magnum] How to document 'labels' > > Hi all, > > This is a continued discussion from the last team meeting. For recap, > ‘labels’ is a property in baymodel and is used by users to input additional > key-pair pairs to configure the bay. In the last team meeting, we discussed > what is the best way to document ‘labels’. In general, I heard three > options: > > 1. Place the documentation in Magnum CLI as help text (as Wangqun > proposed [1][2]). > 2. Place the documentation in Magnum server and expose them via the > REST API. Then, have the CLI to load help text of individual properties > from Magnum server. > 3. Place the documentation in a documentation server (like > developer.openstack.org/…), and add the doc link to the CLI help > text. > > For option #1, I think an advantage is that it is close to end-users, thus > providing a better user experience. In contrast, Tom Cammann pointed out a > disadvantage that the CLI help text might be easier to become out of date. > For option #2, it should work but incurs a lot of extra work. For option > #3, the disadvantage is the user experience (since user need to click the > link to see the documents) but it makes us easier to maintain. I am > thinking if it is possible to have a combination of #1 and #3. Thoughts? > > [1] *https://review.openstack.org/#/c/307631/* > <https://review.openstack.org/#/c/307631/> > [2] *https://review.openstack.org/#/c/307642/* > <https://review.openstack.org/#/c/307642/> > > Best regards, > Hongbin > > ------------------------------ > Rackspace International GmbH a company registered in the Canton of Zurich, > Switzerland (company identification number CH-020.4.047.077-1) whose > registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland. > Rackspace International GmbH privacy policy can be viewed at > www.rackspace.co.uk/legal/swiss-privacy-policy - This e-mail message may > contain confidential or privileged information intended for the recipient. > Any dissemination, distribution or copying of the enclosed material is > prohibited. If you receive this transmission in error, please notify us > immediately by e-mail at ab...@rackspace.com and delete the original > message. Your cooperation is appreciated. > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > >
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
