Add documentation for checkout project and DB changes

docs/amy_database_structure.md

@@ -201,23 +201,36 @@ The primary tables used in AMY (that will appear in most queries) are those that
 
 * `workshops_trainingrequirement`  Lists all available steps towards Instructor certification (Training Event, Welcome Session, etc.)
     * `id`  Sequential, automatically assigned integer.
-    * `name` Name of requirement (*DC Homework*, *LC Demo*, etc.)
-    * `url_required` Notes whether a URL is required for this type of training requirement.  This only applies to the *Lesson Contribution* requirements.
+    * `name` Name of requirement (*Demo*, *Welcome Session*, etc.)
+    * `url_required` Notes whether a URL is required for this type of training requirement. Currently, no requirements require a URL, but some *Get Involved* activities do (see below).
     * `event_required` Notes whether an event is required for this type of training requirement.  This only applies to the *Training* (the actual event they attended).
+    * `involvement_required` Notes whether an activity must be provided for this type of training requirement. This only applies to the *Get Involved* requirement where multiple different activities are acceptable.
 
-* `workshops_trainingprogress` Connects `workshops_trainingrequirement` and `workshops_person` to show what Persons have completed what steps of the checkout process.
+* `trainings_involvement` Lists all activities that are accepted as part of the *Get Involved* training requirement (GitHub contribution, Workshop Instructor/helper, etc.) Note that this table uses the `trainings_` prefix, rather than `workshops_`.
+    * `id`  Sequential, automatically assigned integer.
+    * `name` A short name for the activity (*GitHub Contribution*, *Community Meeting*, etc.)
+    * `display_name` A fully descriptive name for the activity (e.g. *Attended an Instructor meeting, regional meetup, or other community meeting*)
+    * `url_required` Notes whether a URL must be provided for this type of activity.
+    * `date_required` Notes whether a date must be provided for this type of activity. Currently, all activities require a date.
+    * `notes_required` Notes whether text notes must be provided for this type of activity (such as when tracking an activity that is not covered by the existing options). These notes can come from either the trainee or an administrator.
+
+* `workshops_trainingprogress` Connects `workshops_trainingrequirement`, `trainings_involvement`, and `workshops_person` to show what Persons have completed what steps of the checkout process.
     * `id`  Sequential, automatically assigned integer.
     * `created_at` and `last_updated_at`  Dates the record was created and last updated. Automatically generated by database.
     * `state` State of the trainee's progress.
         * `p`: pass
         * `a`: ask to repeat
         * `f`: fail
         * `n`: not evaluated yet
-    * `url` Only for *Lesson Contribution* requirement; links to the trainee's GitHub contribution
-    * `notes` Any human generated notes
-    * `event_id` id of the event this trainee was at.  This is linked to the `workshops_event` table
     * `requirement_id` id of the requirement that is being recorded. This is linked to the `workshops_trainingrequirement` table
+    * `involvement_type_id` only for *Get Involved* requirement, id of the activity that is being recorded. This is linked to the `trainings_involvement` table
     * `trainee_id` id of the trainee being evaluated.  This is linked to the `workshops_person` table
+    * `url` Link to a GitHub contribution, workshop website, etc.
+    * `event_id` id of the event this trainee was at.  This is linked to the `workshops_event` table
+    * `date` only for *Get Involved* requirement, the date of the activity (first day if the activity covered multiple days)
+    * `trainee_notes` only for *Get Involved* requirement, notes submitted by the trainee
+    * `notes` Notes written by an administrator
+
 
 ### Term
 

docs/design/database_models.md

@@ -209,7 +209,8 @@ Represents a requirement that a prospect future instructor need to pass.
 This model also falls into `trainings` domain.
 
 ### `TrainingProgress`
-Intermediate table for M2M between persons and training requirements. Indicates "pass",
+Intermediate table for M2M between `Person`, `TrainingRequirement`, and optionally 
+`Involvement`. Indicates "pass",
 "fail", or "asked to repeat" progress of a person over a particular requirement.
 Once all required requirements are passed, person can become an instructor.
 
@@ -346,3 +347,12 @@ list of choices is maintained as `ACTION_CHOICES`.
 ### `RQJob`
 Represents a [`python-rq`](https://python-rq.org/) job. This job is identified by UUID
 and links to Redis entry maintained by RQ library.
+
+----------------------------------------------------------------------------------------
+
+## Training application - `trainings/models.py`
+
+### `Involvement`
+
+Represents an activity that can be completed as part of the Get Involved step of 
+Instructor Training checkout. Referenced by [`TrainingProgress`](#trainingprogress).

docs/design/projects/2023_instructor_checkout_changes.md

@@ -0,0 +1,56 @@
+# Instructor Checkout Changes
+
+[GitHub project](https://github.com/carpentries/amy/projects/12).
+
+In mid-2023, the checkout requirements for Instructor Training were updated. As the relevant changes were made to AMY to support this update, the project also expanded to include improvements to the training progress view for trainees.
+
+## Checkout steps
+
+### Previous design
+
+Three steps:
+* Lesson Contribution (submitted by trainee through AMY)
+* Community Discussion (attendees submitted by host through a Google Form)
+* Demo (attendees & pass/fail assessment submitted by host through a Google Form)
+
+These steps were defined as `TrainingRequirement`s and progress by trainees was stored as `TrainingProgress` objects.
+
+### New design
+
+Three updated steps:
+* Get Involved - any contribution, such as a GitHub contribution, supporting a workshop, or attending a Community Discussion (submitted by trainee through AMY)
+* Welcome Session (attendees submitted by host through a Google Form)
+* Demo (attendees & pass/fail assessment submitted by host through a Google Form)
+
+The "Community Discussion" `TrainingRequirement` was renamed to "Welcome Session," but otherwise left unchanged. 
+
+The "Lesson Contribution" `TrainingRequirement` was changed more significantly. First, it was renamed to "Get Involved." Second, a new model `Involvement` was developed to store the different activities that a trainee might complete as part of this step. The `TrainingProgress` model was then updated to store an `Involvement` if needed, plus a possible date, URL (already supported), and notes from the trainee. Finally, the submission form on the instructor dashboard was updated to allow the trainee to submit their activity under the new system.
+
+## Training Progress view
+
+### Previous design
+
+A trainee could see what steps they had passed. Any other step status was shown as 'not passed yet.'
+
+The 90-day checkout deadline was not shown on the page; this deadline was only communicated by email.
+
+The Lesson Contribution submission form was always available, and no detail of previous submissions was visible. This led to confusion: some trainees would make multiple submissions, or be unsure if their submission had gone through.
+
+There was also no validation that the lesson contribution URL was associated with a GitHub repository owned by The Carpentries. The Instructor Training Team would often have to contact trainees to explain this error and ask them to resubmit.
+
+### New design
+
+The updated view was updated to show the state (passed/not evaluated yet/asked to repeat/failed) of each step. If training was passed, the page also displays the 90-day checkout deadline.
+
+A summary of the trainee's Get Involved submission (if present) was added.
+
+The Get Involved submission form (which replaced the Lesson Contribution submission form) was moved to a separate view. This allowed edit and delete functionality to be added to un-evaluated submissions. Checks were also added to prevent a trainee from making multiple submissions unless requested to do so.
+
+Finally, validation was added to ensure submissions of GitHub contributions include a URL associated with a [Carpentries GitHub repository](https://docs.carpentries.org/topic_folders/communications/tools/github_organisations.html).
+
+## Other changes
+
+Also as part of this project:
+* 'Discarded' status field was removed from `TrainingProgress`
+* 'Evaluated by' field was removed from `TrainingProgress`
+* Deprecated lesson-program-specific `TrainingRequirement`s were removed (e.g. "SWC Demo" or "LC Homework")