[jboss-jira] [JBoss JIRA] (AS7-5112) Add deprecation information to management API metadata

[Jeff Mesnil (JIRA)]

    [ https://issues.jboss.org/browse/AS7-5112?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12715550#comment-12715550 ] 

Jeff Mesnil commented on AS7-5112:
----------------------------------

I think the "deprecated-replacement" property still need to be a (likely i18ned) free-form text. e.g. in the messaging subsystem, I want to deprecate an attribute and replace it by a child subresource. Having a sentence is the best way to transmit this change:

I also think we MUST have the version in which the attribute was deprecated. I don't think it is a good idea to make a promise about when this item will be removed. We could have decided it'd be removed in 1.3.0, then we cut this release without removing the attribute by lack of time and now we have to update the attribute *just* to change its removal version.
I'd prefer we state the version when the attribute is deprecated and make *no promise* about when it is removed.

I'd also remove the deprecated property: having the deprecated-since prop is enough to know the attribute is deprecated.
For my messaging's deprecated attribute, that'd give:

{noformat}
name: roles
type: OBJECT
value-type: ...
deprecated-since: X.Y.Z
deprecated-replacement: Use the role children resources instead.
{noformat}

or depending on the complexity we want for the deprecated information:

{noformat}
name: roles
type: OBJECT
value-type: ...
deprecated: {
  since => "X.Y.Z",
  message => "Use the role children resources instead."
}
{noformat}


I have no strong opinion yet on whether the version should be the subsystem management API or AS version.





                
> Add deprecation information to management API metadata
> ------------------------------------------------------
>
>                 Key: AS7-5112
>                 URL: https://issues.jboss.org/browse/AS7-5112
>             Project: Application Server 7
>          Issue Type: Feature Request
>          Components: Domain Management
>            Reporter: Brian Stansberry
>            Assignee: Tomaz Cerar
>             Fix For: 7.3.0.Alpha1
>
>
> Add metadata describing that we have deprecated:
> 1) Resources
> 2) Attributes
> 3) Operations
> 4) Operation parameters
> We'll need to sort out exactly what info to provide. We can declare in what management API version an item was deprecated, and provide some localized text explaining. More problematic would be info on what "version" the item will be removed in (outside of vague wording in the description text). Probably including such info would be a mistake; prone to error.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira