[openstack-dev] [heat] Uniform style of README file for contrib resources
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
Re: [openstack-dev] [heat] Uniform style of README file for contrib resources
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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev signature.asc Description: This is a digitally signed message part ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [heat] Uniform style of README file for contrib resources
On 30 July 2014 16:21, Angus Salkeld angus.salk...@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? 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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [heat] Uniform style of README file for contrib resources
On Wed, 2014-07-30 at 17:05 +0400, Sergey Kraynev wrote: On 30 July 2014 16:21, Angus Salkeld angus.salk...@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@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
