Change Request Application
Allow to request changes in pages that needs approval to be published. |
Type | XAR |
Category | Application |
Developed by | |
Active Installs | 1 |
Rating | |
License | GNU Lesser General Public License 2.1 |
Compatibility | XWiki 13.6+ |
Table of contents
Description
This extension allows to request changes on a page without publishing them right away: people have to approve the changes to publish them.
Usage
Create change request
Users who don't have edit rights, can now edit pages by using the button available instead of the edit menu for them. The editor then do not display the usual save buttons, but provide a "Save as change request" button, which opens a window where to fill the title and description of the change request for saving it.
Users who have edit rights, can also save their editions as a change request by using the same "Save as change request" button available in the editor, along with the other save buttons. When saving as change request, it's possible to either create a new change request, or add the changes to an existing change request. Note that when creating a new change request it's possible to mark it as "Draft": setting this status will prevent the change request to be reviewed until you mark it as ready.
Find change requests
It's possible to get a list of all change requests by accessing the change request application.
It's also possible to see the change requests containing modification for a specific page, by looking on the dedicated tab on the bottom of the page
Edit change requests
It's possible to edit a change requests for performing three different actions: changing the status of the change request, editing the documents to perform other changes, or fixing conflicts.
Change the status
There is currently 4 different status for a change request:
- draft: this is used when a change request is still a work in progress. In that state it cannot be merged or reviewed.
- ready for review: as it indicates, this is used when the change request can be reviewed or merged. It's still possible to also edit the files.
- merged: this status indicates that the change request has already been merged, so no more action are possible on it.
The status is set to merged automatically when merging the change request. Now an author can set a change request to Draft or Ready for review manually depending on the need. The button for changing the status is under the "Checks" tab of the change request.
changerequest-draft-checks.png
changerequest-status-ready.png
Edit documents
When it's possible to edit documents, the list of file changes display a pencil next to the link of each document included in the change request. Clicking on the link will open an editor with the current state of the document in the change request, and saving automatically link the changes to the current change request.
changerequest-filechanges-editable.png
Fix conflicts
Some conflicts could occur between the version of the document in the change request, and the version of the document published. This might happen in particular if the published document has been edited after the change request has been created.
Those conflicts are listed in the "Checks" tab of the change request. Next to each file concerned by a conflict, a button allows to open a modal for choosing a conflict resolution. The resolution will only concerns the part involved in the conflict: all parts of the document that can be merged automatically without conflict will be. The modal allows then to chose which version to keep for the parts involved in a conflict: either the version modified in the change request, or the version currently published. It's also possible, when the conflicts concerns the content of the document, to chose a custom resolution for each conflict.
changerequest-conflict-check.png
changerequest-fix-conflict.gif
Review change requests
Change requests must be reviewed so they are approved or not for being merged. All reviews are displayed in the "Reviews" tab, and a button to perform a new review is also available there. A review consists in choosing if it's an approval or if the change request needs to be modified and provide some comment. The author of a review can later mark a review as outdated if some changes occurred on the change request, or if they changed their mind. On the same way, it's possible to restore a review marked as outdated. Note that the reviews marked as outdated are not considered for the approval strategies to chose if the change request can be merged or not.
changerequest-review-approved.png
changerequest-review-modal.png
changerequest-review-changerequested.png
Merge change requests
A change request can be merged if all checks conditions are satisfied. Right now the conditions are the following:
- the change request status must be "ready for review"
- there must be no conflict between the file changes of the change request and the published documents
- the approval strategy condition must be met
Even if those conditions are met, only people with appropriate rights can merge a change request:
- people needs Approve Change Request right
- people needs Edit right on all pages involved in the change request
If all those conditions are met, then it's possible to merge by clicking on the merge button: a new version of the document is automatically created with the changes provided by the change request.
changerequest-ready-for-merging.png
changerequest-not-ready.png
Notifications
Create change request
It's possible to receive notifications when a new change request is created on a watched page, the notification has to be enabled first from the notification settings.
Edit change request
XWiki 0.3+ It's possible to receive notifications when a watched page is edited and the modifications added in an existing change request, the notification has to be enabled first from the notification settings.
Administration
Rights
Two rights are provided by this extension:
- Change Request right: this right is allowed by default, and it enables the capability to create a change request
- Approve Change Request right: this right is denied by default, it allows people to merge a change request, to publish the changes.
Approval strategies
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.
You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Release Notes
v0.4
v0.3
v0.2
v0.1
Dependencies
Dependencies for this extension (org.xwiki.contrib.changerequest:application-changerequest-ui 0.4):
- org.xwiki.contrib.changerequest:application-changerequest-default 0.4
- org.xwiki.contrib.changerequest:application-changerequest-notifications 0.4