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 > [email protected] > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
signature.asc
Description: This is a digitally signed message part
_______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
