<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On 30 July 2014 16:21, Angus Salkeld <span dir="ltr"><<a href="mailto:angus.salkeld@rackspace.com" target="_blank">angus.salkeld@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="">On Wed, 2014-07-30 at 13:41 +0400, Sergey Kraynev wrote:<br>
> Hello guys.<br>
><br>
><br>
> In the last time I meet again change related with changing content of<br>
> README for Docker resource.<br>
><br>
><br>
><br>
> <a href="https://review.openstack.org/#/c/110541/" target="_blank">https://review.openstack.org/#/c/110541/</a><br>
<br>
</div>I can ditch mine, just making a change after helping someone<br>
on IRC through it.<br></blockquote><div><br></div><div>I don't mind about your change. It remembered me about current situation with README files.</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div class=""><br>
><br>
> <a href="https://review.openstack.org/#/c/101144/" target="_blank">https://review.openstack.org/#/c/101144/</a><br>
><br>
><br>
><br>
> Both changes try to improve current description.<br>
> I looked on other README files in contrib directories and met that all<br>
> instructions try to explain<br>
> information which is available here [1].<br>
> This and some other points pushed me on the follow ideas:<br>
><br>
><br>
> - Should we provide some commands like in docker's README which will<br>
> add required path to plugin_dirs ?<br>
<br>
</div>IMO no, it is really simple and this just makes it look harder than it<br>
is.<br>
<div class=""><br>
><br>
><br>
> - Should we have several specific interpretations of [1] or will be<br>
> better to add reference on existing guide and<br>
> mention that some "really specific" notes?<br>
><br>
><br>
> - Should we leave empty sections? (For example, [2])<br>
><br>
><br>
> - Should we add README for barbican resources?<br>
><br>
><br>
> - How about one uniform template for README files?<br>
<br>
</div>can't we just have one contrib/README (at least for the installing<br>
part)?<br></blockquote><div><br></div><div><br></div><div>I wanted to suggest this way, but what about some specific keys </div><div>(keystone plugin require additional change in heat.conf).</div><div>And I correct understood that you offer to leave other information (not installation) in own README files?</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div><div class="h5"><br>
> I think that the right way to have list of allowed sections for README<br>
> with fixed names.<br>
> In my opinion it helps other developers and users with using all<br>
> contrib resources, because they will know what find<br>
> in each section.<br>
><br>
><br>
> I suggest to use follow structure (Note: if section is empty you just<br>
> should not use this section):<br>
><br>
><br>
> # Title with name of resource or for what this resource will be used<br>
>      (After this title you should provide description of resource)<br>
> ## Resources     <- constant name. This section will  be used if<br>
> plugin directory contains more then one resource (F.e. rackspase<br>
> resources)<br>
> # Installation       <- constant name. What we should do for using<br>
> this plugin. (Possible will be enough to add link [1] instead sections<br>
> below)<br>
> ## Changes in configuration      <- constant name. Which files and How<br>
> we should change them. (Possible will  be enough to add link [1])<br>
> ## Restarting services             <- constant name. Names of<br>
> services, which should be restarted.<br>
> # Examples                              <- constant name. Section for<br>
> providing template examples (not full template, just definition of<br>
> contrib resource)<br>
> # Known issues                      <- constant name. All related<br>
> issues.<br>
> # How it works                         <- constant name. If you want<br>
> to tell some mechanism about this resource.<br>
> # Notes                                <- constant name. Section for<br>
> information, which can not be classified for sections above.<br>
><br>
> I understand, that it's just README files, but I still think that it's<br>
> enough important for discussion. Hope on your thoughts.<br>
><br>
<br>
</div></div>yeah, they are inconsistent.<br>
<br>
-Angus<br>
<div class=""><br>
><br>
><br>
><br>
> [1] <a href="https://wiki.openstack.org/wiki/Heat/Plugins#Installation_and_Configuration" target="_blank">https://wiki.openstack.org/wiki/Heat/Plugins#Installation_and_Configuration</a><br>
> [2] <a href="https://github.com/openstack/heat/tree/master/contrib/rackspace" target="_blank">https://github.com/openstack/heat/tree/master/contrib/rackspace</a><br>
><br>
><br>
> Regards,<br>
> Sergey.<br>
</div>> _______________________________________________<br>
> OpenStack-dev mailing list<br>
> <a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br></div></div>