[openstack-dev] [heat] Uniform style of README file for contrib resources
Angus Salkeld
angus.salkeld at RACKSPACE.COM
Wed Jul 30 12:21:14 UTC 2014
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 at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: This is a digitally signed message part
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140730/bcc4fda6/attachment.pgp>
More information about the OpenStack-dev
mailing list