Create flow chart covering all edge cases on new article creation

[taoeffect]

Problem

When someone first creates a subject but doesn't create an article, and someone else comes in and wants to create an article, how do we handle this under the hood with repositories?

Solution

We want to provide the same UX to all users when there are no articles shown, regardless of whether they created the subject or not.

Create a flow chart covering all edge cases per this comment:

Create a generalized algorithm for handling this.

This method prevents multi-root trees from occurring.

---

Alternatively - allow the first person to actually submit the article to become the root. This requires changes to how the backend works.

Handle the edge case where two or more people are working on the first article at the same time, Person A gets root, Person B then should be told that they can't create the article because someone else already did, to go back in the UI and send a CR, or fork the one that was created.

[pedrogaudencio]

I'm proposing this user flow, let me know if it's clear and makes sense. In the Does subject have root article? decision, I added two possibilities but I guess we'll go only for one; in any case we should notify the user that an article was submitted (in the meantime) before theirs so that they decided to either fork it or create a CR.

flowchart TD
    Start([User wants to contribute]) --> CheckIntent{What does user want?}

    CheckIntent -->|Create subject only| CreateSubject[Submit subject creation form]
    CheckIntent -->|Create article| CheckSubject{Does subject exist?}

    CreateSubject --> SubjectCreated[Subject created without article]
    SubjectCreated --> Done1([Subject available for articles])

    CheckSubject -->|No| CreateWithArticle[Create subject + article together]
    CheckSubject -->|Yes| CheckRoot{Does subject have root article?}

    CreateWithArticle --> SubmitArticle[Submit article]
    CheckRoot -->|No - first article| SubmitArticle

    SubmitArticle --> RaceCheck{Root article exists?}

    RaceCheck -->|No - won race| BecomeRoot[User becomes root repository owner]
    RaceCheck -->|Yes - lost race| RaceError[Error: Root article already created]
    BecomeRoot --> Done2([Article published as root])

    CheckRoot -->|Yes - has root| CreateFork[Submit article]

    RaceError --> UserChoice{User chooses}

    UserChoice -->|Go back| SubmitCR[Submit Change Request to root article]
    UserChoice -->|Fork| ForkExisting[Fork the existing root article]

    SubmitCR --> Done3([Change Request submitted])
    ForkExisting --> Done4([Fork created])

    CreateFork --> AutoFork[System automatically creates fork]
    AutoFork --> ForkCreated[Article published as fork]
    ForkCreated --> Done5([Fork linked to root repository])

    style CreateSubject fill:#e1f5ff
    style CreateWithArticle fill:#e1f5ff
    style SubmitArticle fill:#e1f5ff
    style CreateFork fill:#e1f5ff
    style AutoFork fill:#fff4e1
    style BecomeRoot fill:#e8f5e9
    style ForkCreated fill:#e8f5e9
    style RaceError fill:#ffebee
    style UserChoice fill:#fff9c4

Loading

Eventually we can maybe have article drafts saved as WIP in hidden forks or private repositories so that progress isn't lost; then these can be submitted as forks or CR directly.

Let me know your thoughts @taoeffect @pieer @eighttrigrams @dotmacro.

[taoeffect]

Nice mermaid graph! Quick feedback: when the root article already exists, I'd not give the user a choice between CR and fork, I'd just fork. The likelihood of the article being remotely similar to the other one that made it in is very small.

[pedrogaudencio]

Separate User Steps Explanation

It might seem weird that the UX separates "creating a subject" from "creating an article" but in reality we are following Gitea's behaviour:

Gitea	Forkana
User creates a repository	User creates a subject and (empty/hidden) repository
User adds a README.md file and commits	User writes an article and submits it

Hence we have two separate steps. In the UI, we first "Create subject":

And only then "Create article":

So it might happen that there is some delay between these steps (by the creator of the subject), hence the need for this granularity (see flowchart).

Proposal

Simplified the user flow in the step if Root article exists? (Was root article created in the meantime?) is true, then System automatically creates fork, removing the option to either fork or create a CR in that case:

flowchart TD
    CheckSubject{Does subject exist?}

    CheckSubject -->|No| CreateSubject[Create subject]
    CheckSubject -->|Yes| CheckRoot{Does subject have root article?}

    CreateSubject --> SubjectCreated[Subject created without article]
    SubjectCreated --> SubmitArticle[Create _first_ article]

    CheckRoot -->|No - _first_ article| SubmitArticle
    CheckRoot -->|Yes - has root| CreateFork[Fork article]

    SubmitArticle --> RaceCheck{Was root article created in the meantime?}

    RaceCheck -->|No - won race| BecomeRoot[User becomes root article owner]
    RaceCheck -->|Yes - lost race| AutoFork[System automatically creates fork]
    BecomeRoot --> Done1([Article published as root])

    CreateFork --> AutoFork
    AutoFork --> ForkCreated[Article published as fork]
    ForkCreated --> Done2([Fork linked to root article])

    style CreateSubject fill:#4E40FA
    style SubjectCreated fill:#4E40FA
    style SubmitArticle fill:#4E40FA
    style CreateFork fill:#4E40FA
    style AutoFork fill:#4E40FA
    style BecomeRoot fill:#4E40FA
    style ForkCreated fill:#4E40FA

Loading

Optionally we could add copy with "creating a subject does not guarantee ownership of the first article" upon subject creation. Potentially we can also configure a cleanup job to delete subjects with no articles after X days.