Provide general feature and workflow matrix for plugins

pedro-psb commented 1 month ago

While fixing some links in pulp-oci-images, I've came across a reference to "Workflows and Use Cases", which was a set of pages on pulpcore legacy docs. On docs migration, while moving some of these pages, we didnt preserve the notion of a workflow in pulpcore docs.

If I was reading the pulp-oci-images and got to this point (the link is in a section called "Try out a workflow"), I would expect to go to a page with small descriptions of some workflows and links to concrete plugin-implementation for them. And possibly a matrix table, similar to the matrix request for dependencies (https://github.com/pulp/pulpcore/issues/5573), but maybe a little harder to automate.

Problem

No definitive reference for available features and workflows across plugins.

Initial Approach

What I see as possible first steps are:

formalize better what "feature" and "workflow" mean
have a compreehensive grouped list of features and workflows.
edit: gather existing material/discussion on this topic

As a starting point, I tried to organize the titles mentioned in the "Workflow and Use Cases" page linked above.

# definition
workflow: high-level usecases which relies on a set of features
feature: objective capability provided by Pulp
    - builtin: doesn't requires per-plugin-support. 
    - extensions: requires per-plugin-support.

# initial triage
workflows:
    - upload-publish
    - promotion 
features:
    - built-in:
        - user:
            - complex-filtering
            - exposing-content
            - labels
            - repo-versioning
        - admin:
            - repairing-pulp
            - reclaim-disk-space
            - plugin-removal
            - scheduling-tasks
            - troubleshooting
    - extension (requires plugin support):
        - domains-multi-tenancy
        - sign-metadata
        - import-export
        - alternate-content-sources
        - on-demand-downloading

Further steps

Having a compreehensive list of that, we can:

Create a simple Features and Workflows page manually
Create some system to semi-automate this matrix: E.g: each plugin repository can contain a feature-set manifesto which is used by pulp-docs to generate the matrix. This manifesto can include things like tech-preview status, version info (included, modified and deprecated), etc.

mdellweg commented 1 month ago

I do have an issue with the intent here. As history has shown to me, such a feature matrix is created by hand by one individual, because there is no way to automate it. And this individual will put a lot of effort in it and make it very accurate that that point in time. Maybe a group of people even agrees to care about it and keep it up to date. But the reality is, it will get out of date and the more outdated, the harder it gets to update again. This is like balancing a broomstick on your nose. Eventually it will fall on the floor. The only feature we have a forced machine readable record of is domain support. Maybe we should think about that a bit.

pedro-psb commented 1 month ago

I do not disagree it will eventually get outdated, but I dont think this is a reason not to do it. IMO, if we get 80% of today's features and the most popular workflows listed, that's already an UX benefit that will last long. And the federated approach may help a little.

The only feature we have a forced machine readable record of is domain support. Maybe we should think about that a bit.

Are you suggesting we do other features machine-readable?

Anyway, personally I would like to have such a listing specially on the workflows, which is a more high level and readily useful concept.

mdellweg commented 1 month ago

That is exactly the reason not to do it.

Are you suggesting we do other features machine-readable?

Yes, at least think about it.

pulp / pulpcore