Quarterly reports to board MVP

Here is how I think this should generally be implemented:

On a schedule chair(s) of a working group get notifications that it's time to submit the quarterly report for their working group. No notification will be sent out if a quarterly report has already been submitted.
The notification will have a link to the website and will redirect them to a form for submitting quarterly reports.
Chair will fill out the form and click submit
On submission notification(s) will be sent to the board informing them of a new quarterly report.
The chair can edit their report after submission via the site.
Comments can be added to the report by the chair and members of the board
When the report is considered ready for publication a board member or quorum of board members will click a button called "Approve"
Upon approval the report will be created as a file in a public github repository

What's up in the air is where to put the reports while they are private and being collaborated on. There are two forms of storage we could leverage :

A private github repository. Only board members would have access to said repository. This makes sense except that chairs won't be able to collaborate on the document. We could pull the document in via the api, and submit changes, etc. This is going to get really hacky though I do believe and does not support comments, etc.
- Since chairs can not collaborate on a private document submitted to a private repo, we're probably better off keeping this entire process in the application and the details in the database. Even if we pushed the initial reports up to a private repo, we would still need to keep record of the submission in the database so that we know which file to fetch when a chair wants to view/edit said document. Thus, it just makes sense to keep it all in one place. We can facilitate "collaboration" with a simple comments system. It won't have all the fancy features of a traditional collaborative document software but it should be good enough. It would basically function like a github issue. The content which can be edited by the chair is at the top of a page, and comments at the bottom, with no support for threaded discussion. Keep in mind with this suggestion, only the chair would be able to make edits on the submitted document, but to that makes sense anyway, why would we want arbitrary edits from anyone else?

Abstract schema:

working_groups

id (UUID)
name (string)
formed (utc date)
description (text)
email (string)
github (string)
slug (string)

working_group_volunteers

id (UUID) (the member's erlef_app_id in wildapricot)
name (string)
image (bytea)
is_chair (boolean)

working_group_reports
- id (UUID)
- working_group_id (UUID, references working_groups table)
- type - string (e.g., quartlery_report)
- content - the report in markdown format
- submitted_by - (UUID - references working_group_volunteers)
- inserted_at (utc date time)
- updated_at - (utc date time)
- comments - (jsonb[] array of map)
- approvals - (array of UUID)
- logs (jsonb[] array of map - holds each change previously made to the record)

board_members

id (UUID)
erlef_app_id (UUID)
name (string)
image (bytea)

The above can be augmented easily at a later point time. It could facilitate ad-hoc reports to the board.

Normally, I would not suggest such de-normalization but we are wanting to keep this as simple as possible. Likewise, we should not aim for perfection. Good enough is the goal here. Make it work! ™️

How would the notifications be handled?

As discussed on Slack, I would be for using a github repo to store the reports and manage versionning and interactions inside the board with it. This allows us to maintain one source of truth in term of storage but also prvide for free a ticketing system and versionning using git. Also we shouldn't store a report in the db but as a separate file/object so it can be reused by any other tools. So I would suggest the following implementation, maybe more simpler and that can be reused:

create a board repository, all boards members should be part of it
a dashboard handled on the app that handle any interactions we need with a chair: history of submissions, report upload and fetch.
The report is uploaded on the private repository, a ticket is created at the same time. We may just use PR for it. This would automatically trigger a notification to the board.
discussion happen on the ticket.
if a question is needed , the comment could add a specific tag (like `#chair-request$ ) in the ticket that will send a message to the chair. This can be used using the evented github api. Responses are added to the comment/
Once a PR or a ticket is closed, the report will be published to the website. This can again be done using the github api.

The general sense of it is to use a solution that allows us to handle interactions over the reports without too much custom tooling. I don't think we should re-invent a ticket system :) Also we can reuse such pattern for our own request board, to handle support requests from the members. This can eventually be reused by other groups for their need. We cna for example expand it for the stipends.

Thoughts?

How would the notifications be handled?

notifications can be handled the way they are for mail for members and soon events. We just use the fastmail smtp server to send out emails.

As discussed on Slack, I would be for using a github repo to store the reports and manage versionning and interactions inside the board with it. This allows us to maintain one source of truth in term of storage but also prvide for free a ticketing system and versionning using git. Also we shouldn't store a report in the db but as a separate file/object so it can be reused by any other tools. So I would suggest the following implementation, maybe more simpler and that can be reused:

I definitely don't disagree there should be less custom tooling. My concern is around time. Specifically, trying to make the below work would take more time that just making a table in the database. However, the interface(s) will basically be the same. As such, we can try the route you suggested and time box it to a day. If for some reason it becomes problematic then we could fallback to using a table in the database. Thoughts?

EDIT: Note we have to move working groups and volunteers to the database devoid of this. To be clear.

@benoitc As discussed at today's meeting we will MVP this with simply providing an upload report button to chairs on the site vs building a full blown user interface to github. Then we can discuss later how we want to iterate this.

EDIT: Board members will have to communicate with chairs about the report (if necessary) via email for the time being.

erlef / infra-wg