Open Stack

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140730/92f610d3/attachment.html>