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

Simon Urli

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

XWiki 14.3+

Installable with the Extension Manager

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.

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.

Delegate Approvers

A delegation mechanism exists when using an explicit list of approvers. The idea is to avoid a CR to be blocked because explicit approvers are not present for some reasons. So it's possible to define delegates of a user: those delegates will have same power as the real approver, but any review action performed by a delegate will be done "on behalf" of the former approver and will appear as such in the UI. 

In order to enable the delegation mechanism several things must be set in place: 

  1. the XWiki user profile must be extended with one or several dedicated fields for defining the delegates (see the user profile documentation for more information). Note that the new  fields should be of type "List of users".
       2. this or those fields must be filled for the different users
       3. the delegation mechanism should be enabled in the administration, and the name of the new fields should be specified too

Once it's done, the named delegates will see in the UI the same things than an explicit approver.
Note that a delegate can also be delegate of several people, and can be both an explicit approver and a delegate.

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.

Finally it's possible to actually configure a unique Merger user for all change request, directly in the administration: in such case, the rights won't be checked on the current user, but on the configured user. It means that an approver without proper rights will be able to merge any change request since it's the Merger user which will be virtually used to perform the operation. 

Usage

 

Create change request

General remarks

When saving changes as change request, it's possible to either create a new change request, or add the changes to an existing change request.
Also 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.
Finally if one or several open change request already exist concerning the document for which changes are proposed, then an information box will be displayed and will list the existing change requests when opened. 

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. 

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 title and the description

The change request title and description can be edited by clicking on the small pencil next to the title or 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 merged with 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 new changes: it's possible to refresh the change request, so that the changes are compared directly to the version 2.1.
Note that it's never possible to refresh a content automatically, when there is a conflict with the published version of the document: in such case, resolving the conflict will also lead to refreshing the content, but the user choose how to do it.

Note that the action can be done for all changes of the change request, or for a specific document change from the actions in the list of file changes.

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.
Note that a minimum of explicit users approvers might be requested depending on the configuration.

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

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.

It's also possible to reply to comments by clicking on the reply button on any comment.

File changes

You can navigate using the tabs in the file changes: this displays a list of all documents that have been modified in the change request, along with their diff to review the actual change.

Change types

The list of file changes might display the following type:

  • Creation: it means that the document does not exist yet, and will be created when merging the change request,
  • Edition: it means that the document already exist, the change request contains some changes to update it,
  • Deletion: it means that the document exists, but it will be deleted when the change request will be merged,
  • No change: this is a specific type that means that nothing will happen for this document, when the change request will be merged. This type has been introduced to handle some cases when a change request requests for deleting a document, but the document is later on deleted. Refreshing the content will lead to this "No content" type.

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:

  • the list of approvers is updated: those events are triggered whenever the list of approvers is updated, the notification will be sent individually to all people in the previous or current list of approvers,
  • a new 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,
  • existing changes refreshed in a change request: those events are triggered when a change request is refreshed, be it the entire change request or a specific document in it. People who watch the change request can receive the notification, and also people watching a refreshed document if it concerns a specific document,
  • 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
  • a change request is stale: those events are triggered when the dedicated scheduler marks a change request as stale. People who watch the change request will receive it.
  • a change request you are approver of is ready for review: those events are triggered for new change request created as "ready for review", and for change request whose status changed to "ready for review". In both cases, the notifications only targets the explicit approvers.

Autowatch

Note that a change request created by a user is automatically added to its list of watch pages, following its own autowatch configuration

Schedulers

The application provides two schedulers by default that are configured to be executed at noon everyday. 

Detection and notification of stale change requests

A first scheduler aims at detecting the stale change requests and notifying about them. It uses the configuration provided in the administration to compute if the change request is still considered as active or not: basically the computation is based on the date of the last activity on the change request, and on the configured duration since last activity. Note that if there's no configured duration, the scheduler does nothing. By default the configured duration is of 20 days.

When a change request is considered as stale a notification is triggered to all people following that change request, and the date of the detection is recorded inside the change request. If a change request receive activity after it has been marked as stale, the recorded stale date is removed.

Automatic closing of stale change requests

A second scheduler aims at automatically close the stale change requests. There's two possible mechanisms here, depending if the first scheduler configuration is enabled or not (by specifying a duration in the administration).

If the first scheduler is enabled (default behaviour), this scheduler will check all change requests which have a stale date recorded, and it compares it to its own configuration for closing change request (by default 5 days). If the recorded stale date is older than that, it automatically closes the change request with a dedicated status.

If the first scheduler is disabled (its duration configuration is set to 0), then this scheduler basically performs the same operation as the first scheduler for detecting change request, but instead of notifying about them, it closes them: so it compares the last activity of the change request, with the configured duration to consider the change request as stale. If it's older than the accepted duration, it closes it immediately.

Note that a stale change request that has been closed can always be reopened. 

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. 

Change request administration

All the following options are configured inside the "Change request" page of the administration, available under the "Other" section.

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.

Storage location

This allows to specify where the new change requests will be stored. Note that updating this location won't move the existing change requests to it.

Merge user

When configured, defines the user which will be used to actually perform the merge of all change requests: the rights will be checked on this user. By default the field is left blank, which means that the rights are checked with the user seeing the change request. For more information, check the documentation about mergers.

Duration to consider before notifying about stale change requests

Defines the duration in days before a change request is considered as stale when it doesn't receive any activity. This configuration is used for the dedicated scheduler to detect stale change request.
Note that putting 0 here will automatically disable this scheduler job. By default, the value is of 20 days.

Duration to consider before closing stale change requests

Defines the duration in days before a stale change request is automatically closed. This configuration is used for the dedicated scheduler to close stale change request.
Note that putting 0 here will automatically disable this scheduler job. By default, the value is of 5 days.

Use the creation date for stale change requests

When set to Yes, it means that the scheduler used for checking if a change request is stale won't use the date of the last activity, but will use the date of the creation of the change request. Default value is No.

Scheduler user

Specify which user should be used for perform the schedulers tasks. The defined user should have appropriate rights to close the change request automatically. It's highly recommended to set this value, to avoid seeing notifications coming from Guest user.

Delegate Approvers

As explained in the delegation mechanism it's possible to enable it, and the list of fields from XWikiUsers to consider for delegates must be also filled. 

Prevent authors to review their own change requests

When this option is enabled, the authors of a change request are not authorized to review their own work. This option is disabled by default so that they can perform review of their own work and test more easily the extension.

Minimum number of explicit approvers

Specifying a value here implies that explicit users approvers will be used (see the approvers documentation), and that it's mandatory to specify a minimum number of users approvers: this configuration does not apply on group of approvers.
Note that this option might be constraining since it will explicitely block creating a new page from a change request if the number of explicit user approvers is not respected.
By default no minimum is required.

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:

/*
* See the NOTICE file distributed with this work for additional
* information regarding copyright ownership.
*
* This is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of
* the License, or (at your option) any later version.
*
* This software is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this software; if not, write to the Free
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
package org.xwiki.contrib.changerequest;

import org.xwiki.component.annotation.Role;
import org.xwiki.model.reference.DocumentReference;
import org.xwiki.stability.Unstable;

/**
* Perform checks on the new file change to add in a change request.
*
* @version $Id$
* @since 0.9
*/
@Unstable
@Role
public interface FileChangeCompatibilityChecker
{
   /**
    * Check if the given document reference can be added to the given change request.
    *
    * @param changeRequest the change request in which to add new changes.
    * @param documentReference the reference of the document with new changes.
    * @param changeType the type of change to be added in the change request.
    * @return {@code true} if the document can be added to the change request, {@code false} it there's an
    *          incompatibility.
    */
    boolean canChangeOnDocumentBeAdded(ChangeRequest changeRequest, DocumentReference documentReference,
        FileChange.FileChangeType changeType);

   /**
    * Check if the filechange can be added to the given change request.
    *
    * @param changeRequest the change request in which to add new changes.
    * @param fileChange the file change that might be added.
    * @return {@code true} if the filechange can be added to the change request, {@code false} it there's an
    *          incompatibility.
    * @since 0.14
    */
    default boolean canChangeOnDocumentBeAdded(ChangeRequest changeRequest, FileChange fileChange)
    {
       return canChangeOnDocumentBeAdded(changeRequest, fileChange.getTargetEntity(), fileChange.getType());
    }

   /**
    * Provides an explanation as of the reasons of the incompatibility.
    * This method should return a localized explanation, the explanation can be static and the same for all inputs
    * or can be dynamic and provides the very specific incompatibility reason for this specific document.
    *
    * @param changeRequest the change request in which to add new changes.
    * @param documentReference the reference of the document with new changes.
    * @param changeType the type of change to be added in the change request.
    * @return a localized explanation as of the incompatibility reasons.
    * @since 0.14
    */
    String getIncompatibilityReason(ChangeRequest changeRequest, DocumentReference documentReference,
        FileChange.FileChangeType changeType);

   /**
    * Provides an explanation as of the reasons of the incompatibility.
    * This method should return a localized explanation, the explanation can be static and the same for all inputs
    * or can be dynamic and provides the very specific incompatibility reason for this specific filechange.
    *
    * @param changeRequest the change request in which to add new changes.
    * @param fileChange the change to be added.
    * @return a localized explanation as of the incompatibility reasons.
    * @since 0.14
    */
    default String getIncompatibilityReason(ChangeRequest changeRequest, FileChange fileChange)
    {
       return getIncompatibilityReason(changeRequest, fileChange.getTargetEntity(), fileChange.getType());
    }
}

Replication

It's possible to use Change Request with the Replication Application by installing the dedicated extension.

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

v1.0.1

v1.0

v0.15

v0.14

v0.13

v0.12

v0.11

v0.10

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 1.0.1):

Tags:
    

Get Connected