This is an alternative proposal for story #11839.
Instead of being something that sit next to the artifact, the approval table described here is a field by itself and behaves at such. The main difference between the 2 proposal is that the complete version (this one) allows:
- A full logging of changes (who added who to the table, when status was modified, what was changed between 2 changes of a vote)
- A UI integration into the artifact view itself (as a field)
The field comes as a plugin, field must be explicity added to the tracker to be used.
Functional overview
The approval table is a new field that can be instanciated only once in a given tracker. The field can be placed anywhere but it's not recommended to put it in a column (will break layout).
The approval table value can be accessed in:
- Artifact view
- Report
- REST representation
- Webhook representation
All other usage are not possible (no search criteria, no TQL, no SOAP, no charts, etc).
Tracker admin, field configuration
Tracker admin can add the field where he wants. There are not configuration values for this field. Permissions apply:
- Submit/Update: it corresponds to the people who are allowed to create a new approval table, add and remove people, turn on/off the review.
- Read: People that are asked for review must be part of people allowed to read it.
Ask for review
Who: those with write permission (see upper)
When: at any time of artifact life
Where: in artifact view only (not possible from the various modals in scrum, kanban or test management).
In the "Approval table" tab of the artifact, the creator have a autocompleter field that allow to choose people in the list of "registered users". There are no check that selected user can actually access the artifact.
When people are added to the table, the modification be be seen in corresponding changeset (+ notification to people monitoring artifact).
In addition to a list of users, the approval requester have a "free form" where he can write something to reviewers. The change of the text is also displayed in artifact history (+ notification to people monitoring artifact).
Once people are selected, approval requester should click on "start review" to start the review process. One email is sent to all reviewers with the text in "free from" + the link to the approval table. All reviewers are in CC of this email as well as the approval requester. The change of approval table state (from "disabled" to "under review") is recorded in artifact history + notification to people monitoring artifact.
No reminder are sent.
All changes to the table are recorded: addition or removal of reviewer, vote of people, comments, etc. Each action lead to a notification to people that are monitoring the artifact.
Do the Review
As a reviewer, I'll get a specific email (regardless of their tracker/artifact monitoring preferences) asking me to review a given artifact with link to id where I can see:
- Who asked the review
- When it's been requested
- The free text
- The list of all reviewers with
- their name
- the status of their review
- the date and hour of the review.
- the comment they made
For the line of the table that corresponds to my name, I'm able to select either
- Approved
- Rejected
- Will not review
- Under review (can be used to ask for a change)
I can use the follow-up comment of the artifact to comment my vote and I click on the regular "Submit" button of the artifact ot record my vote. This triggers a regular artifact notification with the vote and comment as diff to all people monitoring the artifact.
Reviewers can change there vote at any time as long as the table is still in "under review" state.
Approval or rejection
Note for reviewers: the following behaviour is not tight to "light" or "complete" version of the approval table. It's another approch of the feature thant the one described in story #11839. Each behaviour can be implemented regardless of "light" or "complete" strategy.
At creation, approval table gets the status "Disabled". People can be added in advanced as reviewers.
When approval is actually requested, its status becomes "Under review" (any user that can manage approval can do that).
A user that can manage the approval table can switch the table to "Close" at any time.
There are no other management of status. The action to approve or not the table is left to approval manager when he closes the review. This allow more flexibility on the rules of approval. For instance it can be either 100% of approval, or majority + 1, etc.
When the table is closed, reviewers can no longer change their vote. A notification is sent to people monitoring the artifact.
Artifact life
The approval table lifecycle and the artifact lifecycle are tighly integrated and it will be easy to see the change of artifact between 2 votes. All changes are recorded.
The actual approval of the artifact is left to end users but there will be a clear statement in the history if the final approval doesn't match what was in the approval table
When the artifact is deleted, the approval table is also deleted.
Artifact life
The approval table lifecycle and the artifact lifecycle are completely separated. The artifact can be rewritten completly during the approval table process without impact or notice.
The approval status change (No started, approved, rejected, reset) should be logged as change into the artifact history (Technically: check how it's possible to deal with that).
Same after the end of the approval process, the artifact can be either "Approved" or "Rejected" and it can still be modified.
When the artifact is deleted, the approval table is also deleted.
There are no CSV import/export of approval tables
There are no XML import/export of approval tables