Open Stack

On Wed, 2014-07-30 at 17:05 +0400, Sergey Kraynev wrote:
> 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?

Yes, that seems fine to me. Just stop replicating the install
instructions.

-A

>  
>         
>         > 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
>         
> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: This is a digitally signed message part
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140730/be633ad9/attachment.pgp>