<div dir="ltr"><div>Hello guys.</div><div><br></div><div>In the last time I meet again change related with changing content of README for Docker resource.<br></div><div><br></div><div><a href="https://review.openstack.org/#/c/110541/">https://review.openstack.org/#/c/110541/</a><br>
</div><div><a href="https://review.openstack.org/#/c/101144/">https://review.openstack.org/#/c/101144/</a><br></div><div><br></div><div>Both changes try to improve current description.</div><div>I looked on other README files in contrib directories and met that all instructions try to explain </div>
<div>information which is available here [1].</div><div>This and some other points pushed me on the follow ideas:</div><div><br></div><div>- Should we provide some commands like in docker's README which will add required path to plugin_dirs ?</div>
<div><br></div><div>- Should we have several specific interpretations of [1] or will be better to add reference on existing guide and</div><div>mention that some "really specific" notes?</div><div><br></div><div>
- Should we leave empty sections? (For example, [2])</div><div><br></div><div>- Should we add README for barbican resources?</div><div><br></div><div>- How about one uniform template for README files?</div><div>I think that the right way to have list of allowed sections for README with fixed names.</div>
<div>In my opinion it helps other developers and users with using all contrib resources, because they will know what find</div><div>in each section.</div><div><br></div><div>I suggest to use follow structure (Note: if section is empty you just should not use this section):</div>
<div><br></div><div># Title with name of resource or for what this resource will be used      (After this title you should provide description of resource)</div><div>## Resources     <- constant name. This section will  be used if plugin directory contains more then one resource (F.e. rackspase resources)</div>
<div># Installation       <- constant name. What we should do for using this plugin. (Possible will be enough to add link [1] instead sections below)</div><div>## Changes in configuration      <- constant name. Which files and How we should change them. (Possible will  be enough to add link [1])</div>
<div>## Restarting services             <- constant name. Names of services, which should be restarted.</div><div># Examples                              <- constant name. Section for providing template examples (not full template, just definition of contrib resource)</div>
<div># Known issues                      <- constant name. All related issues.</div><div># How it works                         <- constant name. If you want to tell some mechanism about this resource.</div><div># Notes                                <- constant name. Section for information, which can not be classified for sections above.</div>
<div> </div><div>I understand, that it's just README files, but I still think that it's enough important for discussion. Hope on your thoughts.</div><div><br></div><div><br></div><div>[1] <a href="https://wiki.openstack.org/wiki/Heat/Plugins#Installation_and_Configuration">https://wiki.openstack.org/wiki/Heat/Plugins#Installation_and_Configuration</a></div>
<div>[2] <a href="https://github.com/openstack/heat/tree/master/contrib/rackspace">https://github.com/openstack/heat/tree/master/contrib/rackspace</a></div><div><br></div><div><div dir="ltr">Regards,<div>Sergey.</div></div>
</div>
</div>