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/ 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 ? - 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? 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. [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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev