docs: update concurrent revision doc

docs/concurrentRevisionHandling.md

@@ -16,10 +16,25 @@ An Amendment is opened on a project, and left open while it is being negotiated.
 A solution that would allow us to handle concurrency without user input on conflict resolution was needed. To achieve this, the approach taken is comparable to a git rebase. When committing and pending are in conflict, the changes made in pending are applied on top of the committing form change, as if the committing `form_change` were the original parent of the pending `form_change`. While users commit on a `project_revision` level, the change propogates down to the `form_change` level, so when we're talking about this here it is at the `form_change` granularity, and the heart it takes place in the function `cif.commit_form_change_internal`.
 
 One of the ways our various forms can be categorized would be:
-
 - forms a project can have at most one of (`funding_parameter_EP`, `funding_parameter_IA`, `emission_intensity`, `project_summary_report`)
 - 'project_contact' are either primary or secondary, and have a `contactIndex`
 - 'project_manager' are categorized by `projectManagerLabelId`
 - 'reporting_requirement' have a `reportingRequirementIndex` based on the `json_schema_name`
 
-Form changes can have an operation of `create`, `update`, or `archive`, each of which need to be handled for all of the above categories. This results in several unique cases, which have been explained using in-line in the `commit_form_change_internal` where they have more context.
+Form changes can have an operation of `create`, `update`, or `archive`, each of which need to be handled for all of the above categories. This results in several unique cases, which have been explained case-by-case using in-line in the `commit_form_change_internal` where they have more context. 
+
+After each of the following cases, the `previous_form_change_id` of the pending `form_change` is set to be the id of the committing `form_change`, which leaves every form change with a `previous_form_change_id` of the **last commit** corresponding `form_change`, while preserving the option of a full history by maintaining accurate `created_at`, `updated_at`, and `archived_at` values for all `form_change`.
+
+### Create (the general approach)
+
+If the committing project revision creates a form change that does not exist in the pending revision, for example adding a milestone, then the form needs to be created in the pending revision. In cases such as contacts which have a `contactIndex` associated with them, the index needs to be determined by the existing indices in the pending revision. This will allow the indices to stay sequential if other items were added or removed in the pending revision.
+
+### Update
+
+1. If the committing form change contains the same data as the pending's original parent, then no change to the pending data is needed.
+2. If the committing and pending form changes both have changes from the pending form change's parent, then set the pending form change's new_form_data to be the committing form change's, plus the changes made in the penging form change. The result is what would the data would have been if the pending form change had the committing as it's parent, similar to a git rebase.
+3. If the pending form change hasn't made any changes since its creation, but the committing form change has, set the pending form change's new_form_data to be the committing form change's, as it is the latest information.
+
+### Archive (the general approach)
+
+If the committing `form_change` is being archived, the pending form change can simply be deleted as it never would have been created in the first place had the committing project revision been the original parent of the pending revision.

schema/deploy/mutations/commit_form_change_internal.sql

@@ -175,14 +175,14 @@ begin
       if committing_minus_pendings_parent is not null then
         if pending_minus_pendings_parent is not null then
           -- if the committing and pending form changes both have changes from the pending form change's parent,
-          -- then set the pending form change to be the committing form change, plus the changes made in the penging form change.
+          -- then set the pending form change's new_form_data to be the committing form change's, plus the changes made in the penging form change.
           update cif.form_change
             set new_form_data =
               (fc.new_form_data || pending_minus_pendings_parent)
             where id = pending_form_change.id;
         else
           -- The pending form change hasn't made any changes since its creation, but the committing form change has.
-          -- Set the pending form change ot be the committing form change as it is the latest information
+          -- Set the pending form change's new_form_data to be the committing form change's, as it is the latest information
           update cif.form_change
             set new_form_data =
               (fc.new_form_data)