[Practitioner Guide]: Project state markers (state diagram & overview)

[sjn]

Topic

Overview of project states, to help find out what Practitioner Guides are relevant to read (or write)

Is this a getting started guide or a more advanced guide for experienced users?

Suitable for anyone

Details

Hei!

I just had a chat with @geekygirldawn about potential overlap this project has with the work happening in the CONTRIBUTING.yml spec.

Proposal: Create a state diagram that shows what kind of states we can expect an open source project to be in throughout its course of life.

Maybe something like this? (Terms used here are from relevant taxonomy work by the CPAN Security Group).

stateDiagram-v2
    state "New" as new
    state "Maintained/Active" as maintained
    state "Abandoned/Unmaintained" as abandoned
    state "Archived" as archived
    state "Quarantined" as quarantined
    state "Dormant" as dormant
    state "Under custodianship" as custody
    state "Deprecated" as deprecated
    state "Done" as done

    [*] --> new
    new --> maintained
    archived --> new : Fork
    archived --> maintained : Adopt
    maintained --> new : Fork
    maintained --> deprecated : Deprecate
    maintained --> quarantined
    maintained --> dormant
    maintained --> custody
    maintained --> done
    deprecated --> new : Superseed
    maintained --> archived : Deprecate
    custody --> new : Fork
    custody --> maintained : Adopt
    dormant --> abandoned
    dormant --> maintained : Handoff
    dormant --> new : Fork
    abandoned --> maintained : Adopt
    abandoned --> new : Fork
    archived --> [*]
    done --> [*]
    quarantined --> [*]
    abandoned --> [*]

Loading

I guess this would also require some work on a taxonomy.

Why is this topic important? How will this help people improve their open source project and / or community? Who will benefit from this guide?

I hope this will help users and businesses get an idea of what options are available when selecting what projects to uses and for deciding on what to do with them, depending on the state the project is in.

For example, if a project hasn't had any commits in a long time, a state diagram (possibly accompanied with claims about project state made in a CONTRIBUTING.yml file), the user can get a better idea on why the project has stalled and thereby have better information for deciding to use, contribute, adopt, fund, fork or look for alternatives to the project.

How would you like to see this guide developed?

This is strictly speaking not a "guide" but maybe more a tool for navigating or discovering the guides?

Additional Notes

In the CONTRIBUTING.yml project, we're also looking at this topic. Our intention is to help users and we'd love to ensure that it ends up being something useful that also can help our users find and use the guides in this project.

[geekygirldawn]

@sophia-IV There's some overlap with this and the taxonomy work that might be interesting to pull together :)

[neel212p]

Hi,I’m Neel and I’d like to help develop this Practitioner Guide / state diagram. I can help with [diagram drafting / writing the guide text / creating a CONTRIBUTING example / converting the diagram to an SVG or Mermaid flow].
Is there a preferred format (Markdown / Mermaid / SVG)? Any small task you’d like me to start with?

[neel212p]

Hi — I opened a PR with the initial Practitioner Guide (state diagram + taxonomy): #171

This PR adds practitioner-guides/project-state-diagram.md. Happy to revise if maintainers prefer different formatting/location.