[openstack-dev] [heat] Uniform style of README file for contrib resources

Angus Salkeld angus.salkeld at RACKSPACE.COM
Wed Jul 30 12:21:14 UTC 2014


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.

> 
> 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 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

-------------- 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/bcc4fda6/attachment.pgp>


More information about the OpenStack-dev mailing list