Change Request Application

Version 42.1 by Simon Urli on 2021/09/24 15:51

cogAllow to request changes in pages that needs approval to be published.
TypeXAR
CategoryApplication
Developed by

Simon Urli

Active Installs1
Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Compatibility

XWiki 13.6+

Installable with the Extension Manager

Description

This extension is under heavy development, it's advised to wait a version 1.0 before using it in production: it should only be used for testing the features right now. Also note that on the first versions it's possible to break the way data are stored from one version to another.

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.

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.

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.

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.

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.

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

The approval strategies define the final that has to be met to allow merging a change request, relatively to the review that have been performed. Three strategies currently exist.

Only Approvals

This is the default strategy. With this strategy, each change request needs at least one review to be merged, and all reviews need to be only approval. The change request cannot be merged if there's a single review requesting for changes. 

Accept all

This strategy is mainly for testing purpose: it allows to merge any change request without taking into account the reviews.

Fixed Number Approvals

This strategy allows to merge only when 3 approvals have been gathered. Note that contrarily to "Only Approvals Strategy" a review requesting for changes doesn't prevent the change request to be merged with that strategy.

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:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Release Notes

v0.5

v0.4

v0.3

v0.2

v0.1

Dependencies

Dependencies for this extension (org.xwiki.contrib.changerequest:application-changerequest-ui 0.5):

  • org.xwiki.contrib.changerequest:application-changerequest-default 0.5
  • org.xwiki.contrib.changerequest:application-changerequest-notifications 0.5
  • org.xwiki.platform:xwiki-platform-sheet-ui 13.6
Tags:
    

Get Connected