Comment 19 for bug 1381136

On 19/10/14 10:47, Mike Spreitzer wrote:
> Part of my concern here is that I realized that Heat has some sharp
> edges. Do we really want these sharp edges? I have just done some
> language lawyering, and here is what I have realized.
>
> In the Template Guide --- which is found under Python Developer
> documentation but acknowledged to also be relevant to users --- the
> section about resources
> (http://docs.openstack.org/developer/heat/template_guide/hot_spec.html
> #resources-section) consistently uses the term "resource ID" for what I
> have been calling "resource name". I'll take that as a correction of my
> terminology. The Template Guide also has a definition of the
> get_resource intrinsic
> (http://docs.openstack.org/developer/heat/template_guide/hot_spec.html
> #get-resource), and it consistently uses the term "resource ID" for that
> function's input and uses the term "reference ID" for that function's
> output.
Were in the process of writing the end-user focused template writing guide:
http://git.openstack.org/cgit/openstack/openstack-manuals/tree/doc/hot-guide/source

Feel free to submit reviews for semantic clarifications there. Until the
new hot-guide is published I think we should write all new content in
the openstack-manuals repo and periodically sync back to the developer
template_guide (which will eventually be deleted).

Personally I'd like the spec to change <resource ID> to <resource name>
and for it to state somewhere that resource names are unique within a
stack. We already use <resource name> in other documentation artifacts:

$ heat help resource-show
usage: heat resource-show <NAME or ID> <RESOURCE>

Describe the resource.

Positional arguments:
   <NAME or ID> Name or ID of stack to show the resource for.
   <RESOURCE> Name of the resource to show the details for.

> Python developers see that a Resource has an "id", and fall into the
> habit of saying "resource ID" when we mean that field. I am not the
> only one who has done this; in comment #8 here, Zane followed my lead in
> this direction.
>
> Of course, Resource.id does not hold what the Template Guide defines to
> be the resource's ID. It is actually the resource's reference ID in
> many cases but not all.
>
> It is fast to look up a Resource by it's Resource.id (that being the
> primary key). For a general given resource reference ID, there is no
> general way to look up the reference except by enumerating the resources
> of the stack (presuming the relevant stack is already known) and
> comparing reference IDs. Are we even guaranteed uniqueness?
>
Developer semantics don't map at all to user semantics, so when you
submit your hot-guide changes make sure you make no reference to
Resource.id.