docs(minimal-user-flows): atomic requirements. - #196
Conversation
f2b5de6 to
aa53bf2
Compare
There was a problem hiding this comment.
@caviri here are my comments:
This looks vibe coded and is hard to digest (I read through it, but might have missed something). What comes to my mind in this regard is "Someone has to work hard, either the writer or the reader", in this case it was the reader)
Here are the proposed tickets that I took from it, that are needed for September:
User Stories:
Early Phase (September)
E1. Participant profile
As a participant I want to set my name, affiliation, skills and picture,
so that organisers and teammates know who I am — when I have just joined
an event.
Done when
-
/accountedits display name, affiliation, skills, avatar URL. - Only the URL is stored — no upload — and the image renders.
- A dead URL falls back instead of showing a broken image.
- Teammates and organisers see the profile.
- Editing someone else's profile is refused.
E2. Custom registration form
As an organiser I want to compose my own registration questions, so that I
collect exactly what this event needs — when the standard fields are not
what I have to ask.As a participant I want to answer them once, so that my answers are on
file — when I register.
Done when
- Organiser adds questions with label, type (short text, single-choice,
tags, long text, consent) and a required flag. - Order, types and required flags persist.
- An unanswered required question is refused, naming the question.
- Required consent unticked → refused; optional consent may stay unticked.
- Organiser sees each participant's answers on their row.
- Editing the form later does not destroy answers already given.
-
registerclosed → submitting the form is refused.
Decide. Affiliation and skills are also registration form questions — is the profile
the source of truth, or are they independent?
E3 Email Template
As an organiser I want to write each milestone's email once with
placeholders, so that participants get consistent, event-specific messages —
when the platform notifies people at registration, submission and results.
Done when
- Email sending has been implemented and is coupled to events
- Placeholders substitute per recipient; no raw placeholder reaches anyone.
- Each milestone uses its own template
- An unset template has defined behaviour, visible to the organiser.
Blocked on two answers. Which milestones? The source never enumerates them.
And does anything actually send? If delivery is in scope this grows an SMTP
integration, retries, bounces and preferences. Recommendation: split —
editor plus substitution now, delivery as its own ticket.
E4 Dealines
As an organiser I want to state the event's cut-off dates, so that
participants see one authoritative set — when registration and submissions
have fixed deadlines.
Done when
- All five dates persist: registration opens/closes, proposals close,
preferences close, submissions close. - Participants see the relevant dates.
- A passed deadline behaves as the decision below says, consistently with
the capability gate.
Missing tickets?
- I did not find anything about the branding of the hackathon: what should the organizer be able to brand (Hackathon public page, email template, registration form, etc
- When is the profile form filled, immediately after registration, is it optional?
- When is the registration form filled?
- The user has two profiles: one per hackathon and one on the platform, how do they align?
Late Phase (October)
These tickets are just drafts and have not been fleshed out yet. They need to be discussed in detail later.
L1. Custom submission form
As an organiser I want to define what teams hand in, so that submissions
are comparable field by field — when judging needs a repo, a summary and a
category rather than one free-text box.
L2. Phase transition
As an organiser I want to tick which capabilities a phase opens, so that
advancing to it opens them by itself — when I set the event up once and do
not want to babysit every transition.
L3 Prizes
As an organiser I want to record what is being awarded, so that
participants know what they compete for and placements point at real prizes —
when I set the event up.
L4 Bulk team assignment from CSV
As an organiser I want to assign everyone to teams from one uploaded file,
so that I do not click through a roster of hundreds — when teams are
formed after preference matching.
L5 Participant-facing teams board
As a participant I want a board of the teams and who is on them, so that I
can see who is working on what — when teams have just been formed.
|
|
||
| # Hackathon Setup | ||
| {"type":"action","id":7,"actor":"admin1","title":"admin builds the custom registration form","page":"/my/hackathon/{id}/forms — Registration form (add questions)","provides":"Affiliation (text, required); Experience level (select, required); Skills (tags); Why do you want to take part? (textarea, required); Dietary requirements (text); T-shirt size (select); I accept the Code of Conduct (consent, required); I consent to event photography (consent)","comment":"The admin composes a CUSTOM registration questionnaire — each question carries a label, a type (short text, single-choice, tags, or long text) and whether it is required. Here: Affiliation (text, required), Experience level (single-choice), Skills (tags), a free-text Motivation (required), Dietary needs, and T-shirt size (single-choice), plus two consent checkboxes (Code of Conduct required, photos optional). Participants answer exactly these on their registration form."} | ||
| {"type":"action","id":8,"actor":"admin1","title":"admin builds the custom submission form","page":"/my/hackathon/{id}/forms — Submission form (add questions)","provides":"Repository URL (url, required); Live demo URL (url); One-paragraph summary (textarea, required); Primary category (select, required); Slides (PDF) — upload or link (file-or-url)","comment":"The admin defines the CUSTOM questionnaire teams answer when they turn work in: Repository URL (required), a Live demo URL, a Summary (long text, required), a Primary category (single-choice, required), and Slides (upload or external link). The submission is validated against exactly these questions."} |
There was a problem hiding this comment.
Requirement: a custom submission form. (Needed later)
There was a problem hiding this comment.
Hi @sabinem, we need this earlier, as some questions need to be taken from the participants once they are registered.
A user should be able to edit these options afterwards (but I didn't include that in this basic flow as I don't consider that a priority)
There was a problem hiding this comment.
@caviri This I don't understand. As the submission form is per team. How can be filled in early? It can only be tackled once the teams are assigned. So I would still consider that to come late, or could you please explain what you mean: what would happen at an early stage with the submission form?
There was a problem hiding this comment.
Hi @sabinem, you are right, my bad I got confused by registration form. Submission form can come later, indeed.
| {"type":"action","id":33,"actor":"user1","title":"user1 configures their profile (name, skills, avatar image URL)","page":"/account — edit profile","provides":"displayName, affiliation, skills, avatarUrl","comment":"user1 fills their platform profile. The avatar is set from an image URL hosted by an EXTERNAL provider — a link, not an upload; the platform stores only the URL."} | ||
| {"type":"action","id":34,"actor":"user1","title":"user1 submits the registration form (participation)","page":"/register/{id} — the registration form","provides":"hackathonId, responses, consents","comment":"user1 answers the admin's custom registration questions (affiliation, experience, skills, motivation, diet, T-shirt) and ticks the required consent; the answers are stored against their participation."} |
There was a problem hiding this comment.
Requirement: Custom Registration form, set by hackathon owner?
There was a problem hiding this comment.
Yes, the admin1 in this case\
| # Projects submissions | ||
| {"type":"pages-state","id":55,"at":"Hacking phase — submissions open","phase":"Hacking","capabilities":["create_project_submissions"],"sees":{"anonymous":"the public event page","admin1":"submissions as they arrive","user1":"a “Turn in work” control for Team1","user2":"a “Turn in work” control for Team2"}} | ||
| {"type":"action","id":56,"actor":"user1","title":"user1 turns in Team1's work","page":"/my/hackathon/{id}/submissions","provides":"teamId, projectId, result, form","comment":"user1 submits Team1's work against Project1."} | ||
| {"type":"pages-state","id":57,"at":"user1 turns in Team1's work","who":"Team1","page":"/my/hackathon/{id}/submissions","shows":"Team1's submission appears for organisers to review"} |
There was a problem hiding this comment.
Requirement: Organizers can review submission (later, to be discussed): What does "review" mean?
There was a problem hiding this comment.
Hi @sabinem, organisers receive the submissions, but they aren't published directly on the submissions list page. Organisers can hold some submissions for manual revision to ensure that all the content provided is correct (for instance, that all the links are valid and point to the right document)
| {"type":"pages-state","id":57,"at":"user1 turns in Team1's work","who":"Team1","page":"/my/hackathon/{id}/submissions","shows":"Team1's submission appears for organisers to review"} | ||
| {"type":"action","id":58,"actor":"user2","title":"user2 turns in Team2's work","page":"/my/hackathon/{id}/submissions","provides":"teamId, projectId, result, form","comment":"user2 submits Team2's work."} | ||
|
|
||
| # Voting phase |
There was a problem hiding this comment.
Requirement: Voting implementation (Needed later, to be discussed)
|
HI @sabinem, I'll focus on your user stories for the first iteration. E1. Participant profileHi @sabinem, we need to differentiate between the user profile and the participant profile here. User refers to the general platform profile, while participant refers to the user who registered on the platform. I'd recommend keeping Editing its own profile is optional at this stage. E2. Custom registration form@sabinem I think the Done when is miscopied from above. But I'll keep everything that is not strictly necessary for the platform registration in the custom forms. This includes skills and affiliation. E3 Email TemplateI wrote it above, but I suggest we drop this one for the time being. This is a nice-to-have frontend email generator that can help send private registration links via a third-party email client. It's a workaround for the lack of SMTP integration. But it's fine; we can drop it. E4 DealinesI'll set deadlines to match the time extensions for different phases. This can simplify the actual development. Missing tickets?
Non-essential by now. Let's leave this to the main URL image provided and the content they can place in Markdown.
Let's keep the profile form simple and just with the data from Keycloak. Otherwise, extra fields should be filled right after registration.
The participation form is mandatory after applying for hackathon registration
Replied above. |
|
@caviri Just to be sure that I understand you correctly: Can you please check the following tickets and decisions:
I copied this here from Slack: it was not in the Workflows:
So what is not covered in the tickets above is A1 and A4, can you please comment on these two items, so Team Assignments (A4) should also be ready by August? And what about A1, can you specify this further please? |
|
Hi @sabinem, Regarding E4: Custom Submission Form. My mistake I thought you were referring to Custom Hackathon Registration Form. not Custom Project Submission Form. Regarding A1: A home page whose content can be provided/updated by Valerio and pushed to the platform. This is referring to the hackathon main picture and a public description in markdown (containing emebedded images and youtube embedded videos). This is sort of urgent, as we discuss with Valerio he wouldn't mind finding a programatic way of inserting this content. Do you think we can solve this by seeding this data? or allowing a client to submit via API the hackathon details? I don't like the idea of mixing content with the codebase. And team assigment would be great to have it also by august, it will remove some pressure from the second iteration. We could aim for the CSV/JSON interface and keep a more polish version for later. |
|
@caviri Thanks for answering.
|
2 participants
Hi @sabinem and @Panaetius, I wrote a minimal user flow for a hackathon like the one we are going to host in October. Please feel free to leave comments on the PR if you have any doubts. I omitted many other actions, such as page publication or users checking the projects pages, as I consider this sort of given, but let me know if you need that level of granularity.