There are 4 updates, 2 comments.
 
 
Release Notes Application / cid:jira-generated-image-avatar-1248e7ed-3bd6-469a-a660-27522c6451fa RN-119 Closed

A change cannot be updated once created, so its screenshots cannot be set over REST

 
View issue   ยท   Add comment
 

4 updates

 
cid:jira-generated-image-avatar-db6dc639-2371-4ee2-b2ab-a4baada1495e Changes by Vincent Massol on 10/Sep/26 22:04
 
Documentation in Release Notes: N/A
Documentation: https://www.xwiki.org/xwiki/bin/view/documentation/extensions/dev/release-notes/rest-api/ https://www.xwiki.org/xwiki/bin/view/documentation/extensions/dev/release-notes/java-api/
Resolution: Fixed
Status: Open Closed
 
 

2 comments

 
cid:jira-generated-image-avatar-db6dc639-2371-4ee2-b2ab-a4baada1495e Vincent Massol on 10/Sep/26 22:02
 

The two properties that could not be written after a change or a release note was created now can: the screenshots of a change, whose names must already be attachments of a page the creation itself allocates, and the released and date of a release note, which are only known on the day the version ships.

Added in 2.8:

  • GET and PUT on one release note, at /wikis/<wiki>/releasenotes/<product>/<version>.
  • GET and PUT on one change, at /wikis/<wiki>/releasenotes/<product>/<version>/changes/<entry>. The entry page name is now answered by ChangeRepresentation as entry, so a client never has to parse it out of a page reference.
  • ChangeManager#updateChange and ReleaseNoteManager#updateReleaseNote on the Java API, both also exposed on the script service.
  • ReleaseNotesNotFoundException, mapped to a 404 by the exception mapper.

This answers the open question on this issue: illustrating a change stays a three-call flow and needs no attachment endpoint of ours. Create the change, attach the image through the wiki's generic attachment API against the page the response carries in reference, then PUT the change with the names added.

Two things worth knowing before using it:

  • A PUT replaces, it does not merge. A property the request leaves out is emptied, so send back the change the creation answered with the screenshot names added, rather than a partial body. A change left with no importance is displayed by no release note.
  • The product and the version are never replaced by either endpoint: they locate the page, so changing them would be a move of that page rather than an update of its properties. The content, the title and the template of a release note are left alone too, since an administrator is free to have edited that content.

before.pnglink_attachment_7.gif is what a client could produce before, after.pnglink_attachment_7.gif the same change after one PUT.

 
cid:jira-generated-image-avatar-db6dc639-2371-4ee2-b2ab-a4baada1495e Vincent Massol on 10/Sep/26 22:04
 
The two properties that could not be written after a change or a release note was created now can: the {{screenshots}} of a change, whose names must already be attachments of a page the creation itself allocates, and the {{released}} and {{date}} of a release note, which are only known on the day the version ships.

Added in 2.8:
* {{GET}} and {{PUT}} on one release note, at {{/wikis/<wiki>/releasenotes/<product>/<version>}}.
* {{GET}} and {{PUT}} on one change, at {{/wikis/<wiki>/releasenotes/<product>/<version>/changes/<entry>}}. The entry page name is now answered by {{ChangeRepresentation}} as {{entry}}, so a client never has to parse it out of a page reference.
* {{ChangeManager#updateChange}} and {{ReleaseNoteManager#updateReleaseNote}} on the Java API, both also exposed on the script service.
* {{ReleaseNotesNotFoundException}}, mapped to a 404 by the exception mapper.

This answers the open question on this issue: illustrating a change stays a three-call flow and needs no attachment endpoint of ours. Create the change, attach the image through the wiki's generic attachment API against the page the response carries in {{reference}}, then {{PUT}} the change with the names added.

Two things worth knowing before using it:
* A {{PUT}} *replaces*, it does not merge. A property the request leaves out is emptied, so send back the change the creation answered with the screenshot names added, rather than a partial body. A change left with no {{importance}} is displayed by no release note.
* The product and the version are never replaced by either endpoint: they locate the page, so changing them would be a move of that page rather than an update of its properties. The content, the title and the template of a release note are left alone too, since an administrator is free to have edited that content.

[^before.png] is what a client could produce before, [^after.png] the same change after one {{PUT}}.


Documented on [REST API|https://www.xwiki.org/xwiki/bin/view/documentation/extensions/dev/release-notes/rest-api/], [Java API|https://www.xwiki.org/xwiki/bin/view/documentation/extensions/dev/release-notes/java-api/] and [Script Service|https://www.xwiki.org/xwiki/bin/view/documentation/extensions/dev/release-notes/script-service/]. Only the first two fit the 255-character limit of the Documentation field.