Change Request Application

Version 154.1 by Simon Urli on 2023/04/12 09:35

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

Simon Urli

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

XWiki 14.10.7+

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.

XWiki 1.7+ A new administration option is available which enforces the fact that the approvers defined in the explicit lists do have also the approval right for the page they are defined for. The idea of this option is to allow to control who can be or not an approver by using the right.

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.

You can see below the actual flowchart of the different status. Each square box is a status, the round boxes are the action to perform to switch from one state to another.

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.

Edit approvers

 

XWiki 1.2+ 

If the minimum approvers configuration is set to a value higher than 0, then it's also possible to edit the approvers of a page directly inside a change request, through a Live Data action available in the list of file changes.
This link will automatically open a modal to allow editing the list of approvers and save the changes directly in the new changes proposed in the change request. 

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

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.

Diff

Each changed document can be inspected with a diff view representing the changes that are proposed in this change request. By default all diffs are collapsed, they can be opened just by clicking on the title.
XWiki 1.3+ It's possible to display a rendered diff: a view of the changes where the actual content is rendered. This option needs to be enabled from the administration.

Note that the diff is always computed by taking the latest changes contained in the change request and by comparing them with the version of the page that have been used for creating the changes: so it's possible that the published version of the page evolved since the creation of those changes. In such cases, the diff box contains a label "outdated", meaning that the diff is not necessarily accurate anymore regarding the published version of the page. 

Also if the merge of the changes would lead to a conflict for this document, a "conflict" label is also displayed, but the conflict information is not provided directly in this diff view.

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.

XWiki 1.5+ The comment attached to the diff is now displayed in the timeline with a contextual diff snippet, that is always displayed even if new changes occur leading to outdated diff.

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.

Split change requests

It's possible to split a change request which contains multiple documents. This operation consists in splitting the current change request to separate the changes concerning the different documents: the result will be a different change request for each new document involved in the original change request. The change provided in the original change request are of course kept. Global discussions and review discussions are replicated in all change request created, but specific filechange discussions are kept only to the document they were targeting.
Note that following this action the original change request is deleted, so some links (in particular from notifications) might be broken. 

The split of change request is automatically performed when for some reasons the document in the change request are no longer compatible: this might happen if some rights changed in the published document for example.

XWiki 1.6+ 

This action might be manually triggered through the "More actions" menu by authors of the change request, or by an admin. 

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

Change Request provides various notifications types to allow informing the different actors of the workflow of a change request.
We designed the notifications to target 3 actors:
  - author of a change request
  - explicit approvers
  - watchers of a published page subject to a change request

Event

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

A change request is itself an XWiki page which can be watched for events. We automatically add the change requests to the watched pages of some users following their preferences.

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

XWiki 1.4.5+ Explicit approvers of a page are now also automatically watching change request created for the pages they're approvers of, following their autowatch preferences. However, this does not apply for request for creating pages.

Filter

XWiki 1.4.5+ 

A notification filter is provided and enabled by default. Named "Updates on Change Request Page Filter" this filter prevents to receive standard create/update/comment notifications that happens in the space where Change requests are stored, as they might be perceived as redundant with the change request notifications. Note that the standard delete notification is never filtered.

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.

Enable rendered diff

XWiki 1.3+ This option has been put in place to enable or disable the rendered diff view of changes: by default the option is disabled because it's still experimental and could be expansive in terms of resources. Enabling it allows to view not only the raw diff, but also a diff containing rendered display of the changes.

Security policy to use for the rendered diff

XWiki 1.5+, 1.4.4+ 

This option allows to chose how the document content should be rendered for the rendered diff computation. This choice is about security vs. usability since it might not be wanted to execute scripts proposed in new changes as part of the rendered diff. On the other hand, preventing the execution of any script might lead to having no visual rendering of the changes if the changes are related to page using a sheet with lots of scripts. 

We propose 3 options for performing this trade-off: 

  • Default policy: as indicated, this is the default choice and the most safe one. No script will be executed at all. 
  • Guest right policy: with this choice the page is rendered as if it had been written by the guest user, which is generally the one with the less of privileges. So scripts proposed as part of the changes won't be executed, but scripts coming from other pages written by privileged users (like sheets for example) might be executed. 
  • Change author right policy: this is the less safe choice: it uses the rights of the author of the changes to render the documents. This means that if the author has script right, any script will be executed. 

Accept only approvers that have the approver right

XWiki 1.7+ When checked this option ensures that the selected approvers have approvers right: it allows to forbid some groups of people to became approvers.

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 check that changes can be saved in a change request. It can be for checking compatibility of documents before adding them in an existing change requests, but it can also be to perform some custom checks on a filechange before the creation of a new 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. 

XWiki 1.6+ It's possible to decide the order of execution of those checkers by using the javax.component.Priority annotation: the lower the value used, the higher the priority. 

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.apache.commons.lang3.builder.EqualsBuilder;
import org.apache.commons.lang3.builder.HashCodeBuilder;
import org.apache.commons.lang3.builder.ToStringBuilder;
import org.xwiki.component.annotation.Role;
import org.xwiki.model.reference.DocumentReference;
import org.xwiki.stability.Unstable;

/**
* Define various checks to be performed whenever a filechange is saved: either checks for changes to be added in an
* existing change request, or changes when a change request is about to be created.
* Note that any checker can use a {@code javax.annotation.Priority} to define the order of execution of the checker,
* knowing that in case of failure the reason of the first one failing will be displayed. The lower the priority value,
* the higher the priority of execution.
*
* @version $Id$
* @since 0.9
*/
@Unstable
@Role
public interface FileChangeSavingChecker
{
   /**
    * Class defining a result of the saving checker.
    * This class only aims at holding a reason of the failure in case of failure.
    * In case of success, it doesn't provide any explanation.
    * Note that the explanation should always be a translation key.
    *
    * @version $Id$
    */
   class SavingCheckerResult
    {
        private final boolean canBeSaved;
        private final String reason;

       /**
        * Default constructor whenever the result is a success.
        */
        public SavingCheckerResult()
        {
            this.canBeSaved = true;
            this.reason = "";
        }

       /**
        * Default constructor whenever the result is a failure.
        * @param reason translation key of the explanation why the save cannot be performed.
        */
        public SavingCheckerResult(String reason)
        {
            this.canBeSaved = false;
            this.reason = reason;
        }

       /**
        * @return {@code true} if the check is successful.
        */
        public boolean canBeSaved()
        {
           return this.canBeSaved;
        }

       /**
        * @return the reason why the check was not successful.
        */
        public String getReason()
        {
           return this.reason;
        }

       @Override
        public boolean equals(Object o)
        {
           if (this == o) {
               return true;
            }

           if (o == null || getClass() != o.getClass()) {
               return false;
            }

            SavingCheckerResult that = (SavingCheckerResult) o;

           return new EqualsBuilder()
               .append(canBeSaved, that.canBeSaved)
               .append(reason, that.reason)
               .isEquals();
        }

       @Override
        public int hashCode()
        {
           return new HashCodeBuilder(17, 69).append(canBeSaved).append(reason).toHashCode();
        }

       @Override
        public String toString()
        {
           return new ToStringBuilder(this)
               .append("canBeSaved", canBeSaved)
               .append("reason", reason)
               .toString();
        }
    }


   /**
    * 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.
    */
    SavingCheckerResult 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 SavingCheckerResult canChangeOnDocumentBeAdded(ChangeRequest changeRequest, FileChange fileChange)
    {
       return canChangeOnDocumentBeAdded(changeRequest, fileChange.getTargetEntity(), fileChange.getType());
    }

   /**
    * Check if a change request can be created with the given filechange.
    *
    * @param fileChange the filechange about to be saved for creating the change request.
    * @return {@code true} iff the change request can be created with the given filechange.
    */
    SavingCheckerResult canChangeRequestBeCreatedWith(FileChange fileChange);
}

Replication

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

Limitations

This section gathers information about some known limitations of Change request application. 

Rollback of a change request version

 

TL;DR: it's currently not possible to rollback to a previous version of a change request. 

Basically it's possible to rollback a version of the change request document, as for any XWiki document. However, the whole change request information are not only stored in the main change request document: so reverting a version of that document is not enough if you want to access to a previous version of the change request, before adding some new changes for example.
Such support might be a future work to consider if there's a need, but it's not a priority right now. 

Import of change requests

It's possible to export all data of a change request (except the events) by exporting a change request document and its nested page. However, importing back those information might not work as expected since those information are highly linked to the version of the published document for which changes are requested, and their version.
So users might be very careful when trying to import change request data. 

Deletion of multiple documents

It's currently not possible for a user to request a deletion with multiple nested documents. The reason is merely some lack of time for implementing this feature so it could be part of a future version.

Creation of documents with templates containing hierarchy

The request for creating new documents is not possible when using a template which aims at creating several pages. There's a technical reason under this limitation, which makes such usecase quite complex, so we decided to have this limitation and to ensure user cannot create a change request for such change by accident. 

Edition of a document in an existing change request

Currently this extension does not support resolving conflicts if you're trying to perform changes from a published document, and add the changes to a change request that already contains changes for the same document. So in such scenario, you will most likely obtain an error in the change request save modal informing about the conflicts and asking to create a new change request for your changes.
It's advised if you know you want to add changes to an existing change request, to check in that change request first and perform edition in it directly by clicking on the Edit link on the live data in "File changes" tab, that way you will be able to perform changes on top of the already existing changes of the same document.

Collaborative edition of change request

Right now only the original author of a change request is able to perform changes on the change request. So it's currently not possible to add changes in a change request that you haven't authored.
However this is a considered feature for the future. 

Problems when using Change Request with XWiki Demo package

You might experience some issues when using Change Request on XWiki Demo distribution and more specifically when editing first version of pages included in this distribution (e.g. Main.WebHome or Sandbox.WebHome).
For example, the Rendered diff feature might not work properly, or you might have problems when merging / resolving conflicts. You can follow the status of this limitation by checking this ticket: https://jira.xwiki.org/browse/CRAPP-219

Rename of documents

 

Right now it's not possible to open a change request for requesting a rename / move of a document.
Also in case of renaming / moving a published document for which a change request is opened, the references are currently not updated in the open change request: merging the existing change request will recreate the moved / renamed document (see: https://jira.xwiki.org/browse/CRAPP-168)

Not exact rendered diff display

 

The rendered diff feature aims at giving an insight of what the actual changes of the page will look like. However, for security reasons, we cannot render the changes exactly as they will be once the change will be merged. In particular any macro that uses javascript might not be properly rendered, and any macro that uses specific data from the user won't also be properly rendered. So this view should not be taken as the truth as some differences might appear once published. 

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

v1.6

v1.5.1

v1.5

v1.4.5

v1.4.4

v1.4.3

v1.4.2

v1.4.1

v1.4

The minimum version of XWiki is now 14.10.

v1.3.1

v1.3

v1.2.1

v1.2

v1.1

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

Tags:
    

Get Connected