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