Open Stack

On 30 July 2014 16:21, Angus Salkeld <angus.salkeld at rackspace.com> wrote:

> On Wed, 2014-07-30 at 13:41 +0400, Sergey Kraynev wrote:
> > Hello guys.
> >
> >
> > In the last time I meet again change related with changing content of
> > README for Docker resource.
> >
> >
> >
> > https://review.openstack.org/#/c/110541/
>
> I can ditch mine, just making a change after helping someone
> on IRC through it.
>

I don't mind about your change. It remembered me about current situation
with README files.



>
> >
> > https://review.openstack.org/#/c/101144/
> >
> >
> >
> > Both changes try to improve current description.
> > I looked on other README files in contrib directories and met that all
> > instructions try to explain
> > information which is available here [1].
> > This and some other points pushed me on the follow ideas:
> >
> >
> > - Should we provide some commands like in docker's README which will
> > add required path to plugin_dirs ?
>
> IMO no, it is really simple and this just makes it look harder than it
> is.
>
> >
> >
> > - Should we have several specific interpretations of [1] or will be
> > better to add reference on existing guide and
> > mention that some "really specific" notes?
> >
> >
> > - Should we leave empty sections? (For example, [2])
> >
> >
> > - Should we add README for barbican resources?
> >
> >
> > - How about one uniform template for README files?
>
> can't we just have one contrib/README (at least for the installing
> part)?
>


I wanted to suggest this way, but what about some specific keys
(keystone plugin require additional change in heat.conf).
And I correct understood that you offer to leave other information (not
installation) in own README files?


>
> > I think that the right way to have list of allowed sections for README
> > with fixed names.
> > In my opinion it helps other developers and users with using all
> > contrib resources, because they will know what find
> > in each section.
> >
> >
> > I suggest to use follow structure (Note: if section is empty you just
> > should not use this section):
> >
> >
> > # Title with name of resource or for what this resource will be used
> >      (After this title you should provide description of resource)
> > ## Resources     <- constant name. This section will  be used if
> > plugin directory contains more then one resource (F.e. rackspase
> > resources)
> > # Installation       <- constant name. What we should do for using
> > this plugin. (Possible will be enough to add link [1] instead sections
> > below)
> > ## Changes in configuration      <- constant name. Which files and How
> > we should change them. (Possible will  be enough to add link [1])
> > ## Restarting services             <- constant name. Names of
> > services, which should be restarted.
> > # Examples                              <- constant name. Section for
> > providing template examples (not full template, just definition of
> > contrib resource)
> > # Known issues                      <- constant name. All related
> > issues.
> > # How it works                         <- constant name. If you want
> > to tell some mechanism about this resource.
> > # Notes                                <- constant name. Section for
> > information, which can not be classified for sections above.
> >
> > I understand, that it's just README files, but I still think that it's
> > enough important for discussion. Hope on your thoughts.
> >
>
> yeah, they are inconsistent.
>
> -Angus
>
> >
> >
> >
> > [1]
> https://wiki.openstack.org/wiki/Heat/Plugins#Installation_and_Configuration
> > [2] https://github.com/openstack/heat/tree/master/contrib/rackspace
> >
> >
> > Regards,
> > Sergey.
> > _______________________________________________
> > OpenStack-dev mailing list
> > OpenStack-dev at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140730/6149a2f0/attachment.html>