Change Request Application

Version 77.2 by Simon Urli on 2022/02/04 10:56

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 14.0+

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.

Approvals mechanisms

The whole purpose of this extension is to ensure that changes are reviewed and approved before being published. Hence there is two main distinct features in the extensions:

  • the capability to review and approve a change request: we are calling users who are entitled to do that the approvers
  • the capability merge the changes provided in a change request so that they are published: we are calling those users the mergers

Approvers

There is two distinct mechanisms to define the approvers:

  • by using a specific xobject 
  • by using the Approval right
     
    The first mechanism is the first we check to define if a user is entitled to approve a change or not: each page can have its own list of approvers (users or groups) defined in an xobject. When a change request is created, the list is automatically copied in the change request so that it's used to define the approvers of this change request. Inside the change request, this list can then be updated to add or remove more people as approvers. Moreover, if another change is added from another page which also have a list of approvers, the approvers list of the change request is automatically updated to include them.
    So this mechanism relies entirely on an explicit list of approvers provided for the pages for which a change request is made, or for the change requests themselves.

The second mechanism is more generic, it consists in an extension right, that can be configured at any level (wiki, space or page) and define who can approve changes, when no explicit list of approvers is provided. So this right is never checked when the first mechanism is used.

Note that some Approval Strategies might be adapted for only one of those mechanism.

Mergers

 

The mergers are the people that are able to publish the changes performed in a change request. Those users necessarily needs the proper XWiki Rights for saving the changes to save the changes: if the change request contains editions, then the merger will have edit rights on the concerned page; if it contains deletion, the merger will have delete right on the concerned page. For a given change request, a merger need the right for all the changes included in the change request.

A merger can be an approver as defined previously, but if they are not part of an explicit list of approvers, then they only require to have the approval right to merge a change request. So the Approval Right can also be used as a fallback mechanism to define the mergers when the first mechanism is used for defining approvers.

Usage

 

Create change request

For requesting editions

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.

For requesting page creation

Users who don't have edit rights can request for creating page with a create button looking exactly like the standard create button. The usual UI to chose a type of document, or a template is then displayed and after that the same editor than for requesting editions with the "Save as change request" button. 

If users have edit rights, then the standard UI is displayed for creating a page: users only have to select "Save as change request" in the editor after having chosen the location where to create the page. 

Limitations

Note that right now some limitations exists for creating a page with some templates. The extension doesn't support templates which are using a hierarchy of pages, and template providers which are using something else than the "edit" action>.

For requesting deletions

Users with or without delete rights can request a deletion of a page as part of a change request. In that case, merging the change request will lead to the deletion of the page. Note that only pages that are not considered as technical can be requested for deletion: pages which don't contain any xclass, and that don't belong to extensions. 

Find change requests

Lists of change requests are displayed in various places, using each time a Live Data to allow an easy filtering and sorting of the results.  

List of all change requests

You can get a full list of all change requests created on the wiki by going in the application main page (available through the application panel).

Change requests related to a document

In every document, you can access the list of change requests created for this document, by going into the specific tab at the bottom of the document.
Also note that when several change requests are opened for the same document, an information box listing the other opened change requests is available in the "Checks" tab of the change request view.

Change requests authored by a user

When going to any user profile (including yours), you can see the list of change requests authored by this user. 

Change requests that can be approved by a user

When going to any user profile (including yours), you can see the list of change requests ready for review and that this user is able to approve. Note that both approvals mechanisms are taken into account, so change requests for which the user is an approver will be mixed up with change requests without any approver, but for which the user has rights to approve.

Edit change requests

It's possible to edit a change requests for performing different actions: changing the status of the change request, changing its description, editing the documents to perform other changes, or fixing conflicts. 

Change the status

There is currently 5 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. It's still possible to also edit the files.
  • ready for merging: a change request is automatically updated from ready for review to ready for merging when all the checks are satisfied for allowing to merge it. At this point the change request can still be updated, and it's possible that it rollbacks to ready for review automatically after an update.
  • merged: this status indicates that the change request has already been merged, so no more action are possible on it.
  • cancelled: this status indicates that the change request is no longer active. It cannot be updated anymore, but it can be reopened at any time.

The status is set to merged automatically when merging the change request. Now an author can set a change request to draft, ready for review or cancelled manually depending on the need. The button for changing the status is under the "Checks" tab of the change request.

Change the description

The change request description can be edited by clicking on the small pencil in the description tab. 

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.

Refresh content

A change request can be refreshed at any time: this operation means that all the changes will be checked against the latest version published on the wiki, instead of checking it against the version used to save the changes. 

So for example, imagine a document was published in version 1.1 and a change request was made starting from there. Then a new version 2.1 of this document has been published, introducing some conflicts: it's possible to refresh the change request, so that the changes are compared directly to the version 2.1, in which case the conflicts won't exist anymore since the changes will be applied on top of version 2.1. 

Manage approvers

 

As explained previously, it's possible to define a specific list of approvers for a dedicated page, or for a change request. This is done by selecting "Manage approvers" in the other action menu, and by editing the xobjects to provide the list of wanted users or groups. It's possible to check for a Change request the list of approvers used by checking the Approvers tab.

Review change requests

Change requests are changes meant to be reviewed in order to be accepted or not for publication. The review process generally involve to read the change requests, to maybe comment it, and then to add a review as an approval or as requesting specific changes for it to be accepted in the future.

Read change request

 

The change request homepage displays several information:

  • the status of the change request,
  • its title and description,
  • the timeline of all events that occurs in it
  • the global comments of the change request

You can navigate using the tabs in the filechanges to see what changes have been done displayed as a diff performed between current version published and the version with changes contained in the change request.

Comment

It's possible to add global comments on the change request from the description tab. It's also possible to add specific comments on lines of the diff by going into the diff view and clicking on a specific line. Note that it's possible to use any macro available in XWiki in those comments, including mentioning people.

Approve or request for changes

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.

Check status

The last tab  checks allows to have a global overview of the current status of the change request to determine what prevents it to be merged, and how to fix the situation.
It also contains information, such as the list of other change requests that concerns same document.

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 or needs to be part of the list of approvers
  • people needs Edit right on all edited pages of the change request
  • people needs Delete right on all pages requested for deletion 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.

View right synchronization

In order to protect confidentiality of the pages, view rights of documents are automatically synchronized with the view rights of the change requests created for the documents, so that anyone who could not see a document, could not see the related change request either. The rights are synchronized automatically when a right change is performed in a document which is not a change request, and at change request creation.

However this synchronization mechanism has a limit whenever a change request contains changes related to multiple documents with incompatible view rights: in such case, if the document changes is not yet added, the user will get an error message when trying to add it. But if the change request already exist with multiple documents and the right is changed afterwards so that the compatibility is not kept, then the change request is automatically splitted to only keep one document per change request in order to preserve the rights.

Notifications

The change request application triggers different kind of notifications, that can be individually switched on or off:

  • a change request is created: those events are triggered when a change request is created, it will be displayed for people who watch the page from where the change request was created,
  • new changes has been added to a change request: those events are triggered whenever an existing change request has been edited with new changes. People who watch either the change request itself, or the page involved in the changes can receive those notifications,
  • the change request status has been updated: those events are triggered when the status of a change request changed. People who watch the change request will receive it,
  • a new review has been made: those events are triggered when a review has been performed on a change request. People who watch the change request will receive it.

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. The strategy can be chosen in the Change request page of the Administration

Require 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. 

Merge without constraint

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

Require a fixed number of approvers to approve

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.

Require all approvers to approve

This strategy is meant to be used when the extension is used with a predefined list of approvers for pages that are modified. It checks that all the approvers that are specified in the Approvers list of a change request have approved it, before authorizing the merge. However, if the change request does not rely on an explicit list of approvers, then the strategy automatically falls back to the Require only Approvals Strategy.

Development

Events

The extension is triggering the following events:

  • ChangeRequestCreatedEvent: is triggered when a new change request is created. It's sent with the change request identifier as source, and the change request object as data.
  • ChangeRequestFileChangeAddedEvent: is triggered when a new filechange is added to a change request. It's sent with the change request identifier as source, and the new filechange object as data.
  • ChangeRequestMergedEvent: is triggered when a change request has been merged. It's sent with the change request identifier as source, and the change request object as data. (Note that a ChangeRequestStatusChangedEvent is also triggered when a change request is merged).
  • ChangeRequestMergingEvent: is triggered just before a change request starts the process for merging. It's sent with the change request identifier as source, and the change request object as data.
  • ChangeRequestReviewAddedEvent: is triggered when a new review has been added to a change request. It's sent with the change request identifier as source, and the review object as data.
  • ChangeRequestStatusChangedEvent: is triggered when a change request status has been updated. It's sent with the change request identifier as source and an array containing both the old and the new status. (Note that in case of merging, this event is triggered as part of the process but ChangeRequestMergingEvent and ChangeRequestMergedEvent are also triggered before and after).
  • ChangeRequestUpdatedEvent: is triggered when some change request information are updated such as the title and description. It's sent with the change request identifier as source, and the change request object as data.
  • SplittedChangeRequestEvent: is triggered when a change request has been splitted. It's sent with the original change request identifier as source, and the list of newly created change requests as data.

Checking compatibility of documents

The extension offers a mechanism to enforce the compatibility of documents, before grouping them in the same change request. This mechanism is internally used to ensure to not add in same change request documents that are not sharing the same view rights (see the related documentation). It can be extended so that external constraints are taken into account.
To extend this mechanism, developers need to implement a new component with the following signature:

404: Not Found

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.9

v0.8

v0.7

v0.6

v0.5

v0.4

v0.3

v0.2

v0.1

Dependencies

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

Get Connected