[release/v1] Rename `long_name` attribute to `description`

[mkavulich]

The term long_name comes from the repository's CCPP provenance and is somewhat confusing and ambiguous. Since this is essentially a field for including a detailed description of a variable's use, it is much more clear and straightforward to rename this attribute description.

[gold2718]

The term, long_name, comes from the CF conventions, see section 1.4. I think we should keep it.

[climbfuji]

I agree with @gold2718, I prefer keeping long_name over other descriptors.

[mkavulich]

Thanks for the feedback; this was something brought up from the CGD side and I didn't think to investigate its provenance closely. If it is coming from the CF conventions that is a more solid reason to keep the naming as is, but we are also not married to those conventions, so I'll wait to see if there is some specific reason why long_name should be ditched other than it's somewhat ambiguous compared to description.

[cacraigucar]

One "nuance" which was discussed at our CCPP meeting was that while standard_name is required to match exactly what is in the dictionary, long_name is not required to match across models. By its inclusion in the dictionary, users may feel compelled to include the exact long_name in their models as well since the framework uses the same name in .meta files. We discussed how we do NOT want to change long_name in the Framework. If the dictionary does not give "guidance" on how to populate the long_name field, then users will be more comfortable using names which better describe the variables within their particular models.

The dictionary is describing what the variable "is" to aid users in discovering their correct variable. So the current long_name field is more accurately a description.

When fields are being used within the framework .meta files, the long_name there IS adhering to the CF conventions.

I personally believe that the description in the dictionary and long_name in .meta files are two separate quantities and the place where we need to adhere to the CF conventions is in the Framework itself.

[gold2718]

I find @cacraigucar's argument fairly persuasive. I am okay with this but have a couple of requests.

1. The distinction from and relationship to the long_name metadata argument needs to be clearly documented in the preamble.
2. Every entry gets a description that is -- descriptive.

[climbfuji]

One "nuance" which was discussed at our CCPP meeting was that while standard_name is required to match exactly what is in the dictionary, long_name is not required to match across models. By its inclusion in the dictionary, users may feel compelled to include the exact long_name in their models as well since the framework uses the same name in .meta files. We discussed how we do NOT want to change long_name in the Framework. If the dictionary does not give "guidance" on how to populate the long_name field, then users will be more comfortable using names which better describe the variables within their particular models.

The dictionary is describing what the variable "is" to aid users in discovering their correct variable. So the current long_name field is more accurately a description.

When fields are being used within the framework .meta files, the long_name there IS adhering to the CF conventions.

I personally believe that the description in the dictionary and long_name in .meta files are two separate quantities and the place where we need to adhere to the CF conventions is in the Framework itself.

Ok with that, we need to be crystal clear in our documentation though or it will lead to greater confusion than what we have now.

[mkavulich]

Resolved by #116