Functional overview
This approval table is meant to get a formal agreement of a given artifact. Its used to simplify approval of people on a requirement, a spec, etc.
The approval table is only really used as a way to ensure that a given list of people were OK on something at a point of time. However this information is not used elsewhere (no REST API, no CSV export, no column in report, no chart, no webhook trigger, no workflow/transitions, etc).
From a usage point of view, the only way to have an artifact approval table status is to go on the given artifact and to click on the "Approval table" link in the list of tabs (new to "Artifact", "Children", etc).
There is no automated actions introduced by the approval of an artifact. When an artifact is approved, is visible in the "Approval table" link of the artifact and that's it. If the consequence is to change something on the artifact, it's the duty of the requester to make the update afterward.
The feature comes as a plugin, as long as the plugin is installed, all artifacts in all trackers can have approval tables.
Ask for review
Who can do that: Anyone that can create an artifact in a tracker can create an approval table on an artifact of this tracker.
When: the approval table can only be created after the artifact creation (ie it's not possible to create an artifact & the approval table at the same time).
Where: in the tracker 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.
In addition to a list of users, the approval requester have a "free form" where he can write something to reviewers.
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.
There a no other notification sent. As it's not an artifact update, people monitoring the tracker won't receive an email about this approval table.
There are no reminder sent.
The approval table creator is the only person than can add/remove people to/from the list (+ tracker & project admins). The update of the table itself is not recorded (if someone rejected the doc but was removed after that it's not visible).
Approval table creator can also "reset" the vote of a given user, it's then reverted to "Under review". Resets aren't log either.
Do the Review
As a reviewer, if I click on the link I receive in the mail, I'm accessing the "Approval table" tab where I can see
- Who asked the review
- When it's been requested
- The free form 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 write a comment and to select either
- Approved
- Rejected
- Will not review
- Under review (can be used to ask for a change)
+ Submit button.
At Submit, all reviewers + approval requester are notified of the status of the review + comment if any.
Once the "Approved" or "Rejected" are chosen, it's no longer possible to change for the reviewer. If there is an update to do, the approval creator should reset the original vote.
Approval or rejection
At creation, approval table gets the status "Under review".
When all reviewers approved the artifact, the status of the approval table is switched "Approved". It can happen when
- the last reviewer set "Approved" or "Will not review"
- the approval creator removes the last "Rejected" from the list
When at least one user "Reject", the approval table is switched to "Rejected".
As soon as the table is either "Approved" or "Rejected", the date is recorded and the approval process is stopped (other reviewers cannot modify).
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