Workflows

[SteveALee]

[Updated 2022/03/02]

Flows

(Implementation details are below).

• Add new item
  • a visitor to the WAI website enters details (including their email with explicit permission grant) and submits
  • a reviewer inspects the submission and works with submitter to update if required
  • a reviewer accepts the submission and adds to the current list
  • a WAI site maintainer reviews and adds it to the WAI website
    • OR this could be semi-automated
• Update existing item
  • a visitor to the WAI website enters updated details (including their email) and submits
    • could be using existing submission ref or a new one as long as can identify the updated submission
  • OR a reviewer works with submitter to update the submission as required
• Remove item
  • a reviewer decides unilaterally or with submitter and decides removes
  • Q should all submissions be kept, but deleted ones are marked so as not to appear in the list?

Implementation elements

• current submissions are JSON files in folder found in the GitHub repository for the W3C WAI Website list resource (eg wai-course-list)
  • a submission ref is assigned to each submission and this is used as the filename
• Netlify integration provides CI/CD previews for PRs (eg after submission is made but before WAI site updated)
• the list of current submissions on the WAI website is updated from GitHub when the WAI website is rebuilt and published
• new submissions are created using a HTML form that is part of the list resource on the WAI site
  • support for the submission form is provided by the WAI website Theme and uses standard HTML form submission
  • a extra check is added for at least one checkbox selected in a required group
• on submission, a process creates a GitHub PR with the form data (plus some extra metadata like submission ref)
• GitHub PR features support all aspects of submission discussion, management and update.
• merging the PR to the main branch will make updates appear when the WAI Website is next built ad published.
• GitHub Auth is also used to limit access, with W3C WAI being the repository owners

Scope

• The original project concept only covered Adding a new submission but subsequent Update and Removal are clearly required for on-going maintenance.
• The above implementation allows for all flows but the HTML form is only used for new submissions, updates require working with the JSON data. This is due to a technical limitation of using a static rendered website, but is not insurmountable.
• Similarly, once the HTML form is entered the user should be able to preview the new proposed entry before submitting.
• Could add client side and/or backend validation of submission contents. There are few free text fields though.

[SteveALee]

Straw proposal: from Shadi and @leticiaseixas

• entries for lists (eg. courses, authoring tools, eval tools, ...) are stored as individual JSON files in a directory in the GitHub repo
• vendors can use to a form to provide information about their products (eg. courses, tools, ...), which creates a Pull Request in the repo
• the form can be used to load existing JSON files and to create a Pull Request on existing JSON files, as well as to create new JSON files
• the form is not required, experienced users can do the Pull Requests directly on GitHub or through git etc. to create or update entries
• in any case a GitHub account is needed, which is used to verify the Pull Request submitter (that it is someone from the vendor org)
• repo maintainers check the Pull Requests, possibly with some syntax checker tool to make sure that the JSON files are correctly coded
• approved Pull Requests are merged, and appear in the list; when the JSON file is removed from the directory, it is removed from the list
• (possibly) a link-checker tool that runs periodically or manually?

Comments

• Nit: PRs are a GitHub feature and not part of the underlying git VCS. Branches are through. But the proposal is all have a GH account anyway.
• By submitting list entries as files in git we have a layered approach: it works in a basic way if people can add files, it can be improved by creating some form that creates the files automatically (which we may or may not have time for during the project time).

[SteveALee]

approved Pull Requests are merged, and appear in the list; when the JSON file is removed from the directory, it is removed from the list

The font end for the list page almost certainly wants a single json file so a process is required to generate this file with the source json files in a top level array (or hash). This might be manual or automated.

PRs are a GitHub feature and not part of the underlying git VCS. Branches are through. But the proposal is all have a GH account anyway.

Sure but usually PRs add significant value eg comments, easy diffs and Netlify preview integration. These may or may not be useful for the data. W3C prefer to not have resources held in an external 3rd party silo so might want to check if PRs OK.

By submitting list entries as files in git we have a layered approach:

While useful for technical contributor, github access might put mean non technical submitters off as they would be required to use GitHub which may be a step to far. We also will eventually need "update" and "delete" flows. An eventual solution might provide more friendly Web page only access to all actions. Until then the list maintainer can communicate to non technical submitters via emial and make changes on their behalf.