Hide properties and entities that have been deprecated for 2-3 releases#81
Hide properties and entities that have been deprecated for 2-3 releases#81
Conversation
|
|
|
||
| entityTypeMappings: &entityTypeMappings | ||
| type: array | ||
| x-hide: true |
There was a problem hiding this comment.
I am not sure, if we can already hide it already. BAH is not yet supporting exposedEntityTypes, S/4 is still exposing it...
There was a problem hiding this comment.
Yes, but we would just hide it from documentation. For new adopters, we don't want them to implement / see this. Also it looks like there is now no consumer for it, except BAH using it to create the links (which would be simpler with exposedEntityTypes
Hiding this would greatly help cleaning things up, as it also removes some objects
There was a problem hiding this comment.
I understand, but the support for exposedEntityTypes is not given and we still want the links and we haven't updated all guidelines to use exposedEntityTypes, do we? So documentation is still needed until one can really use exposedEntityTypes.
There was a problem hiding this comment.
Then let's push BAH to support it. And the guidelines should be updated already I guess.. we'd need to check
There was a problem hiding this comment.
@swennemers do you have strong objectsions? I would prefer to do this sooner than later, as it cleans up and reduces chances that deprecated features are used for new developments.
@maiargu - how easy would it be to support in spec-toolkit that we generate the markdown documentation twice, once with and once without hidden content? Is this something we should do from the beginning?
swennemers
left a comment
swennemers
left a comment
There was a problem hiding this comment.
in general +1, but I have doubts on hiding entityTypeMapping yet
|
|
|
||
| ### Changed | ||
|
|
||
| - Hidden deprecated properties from documentation using `x-hide: true`: |
There was a problem hiding this comment.
I think changes done to the UI by appling x-hide don't need to be added to the changelog file, the exposed npm package JSON schema did not change at all for consumers
There was a problem hiding this comment.
I'd still prefer to keep it in, because many read the documentation as a page and the changelog might at least give a hint why some things have now disappeared. Better over-communicate here :) But yes, for JSON Schema / NPM consumption, it's not changing anything
4 participants
Goal is to make the human readable documentation less daunting by hiding properties and entities that have been deprecated for a longer time already. They are just hidden from the documentation and still part of the JSON Schema / Interfaces. So this is not a breaking change, just cosmetic cleanup.
Alternative idea: Generate the documentation twice, so there is also a version where everything can be seen. But by default show the cleaned up version.
Changed
x-hide: true:policyLevelandcustomPolicyLevel(deprecated since v1.9.9) - usepolicyLevelsinsteadentityTypeMappings(deprecated since v1.11.0) - useexposedEntityTypesinsteadsystemInstanceAware(deprecated since v1.12.0) - useperspectiveinsteadEntityTypeMapping,ApiModelSelectorOData,ApiModelSelectorJsonPointer,EntityTypeOrdIdTarget,EntityTypeCorrelationIdTargetpolicyLevel/customPolicyLevelreferences topolicyLevelsin spec indexsystemInstanceAwarereferences toperspectivein access strategy docs and FAQsystemInstanceAware,policyLevel,customPolicyLevel)