Project

Profile

Help

Story #4626

As a [user, dev, plugin writer] I know which user facing features will be documented in core, and in the plugins

Added by amacdona@redhat.com 7 months ago. Updated 6 months ago.

Status:
MODIFIED
Priority:
Normal
Category:
-
Sprint/Milestone:
Start date:
Due date:
% Done:

100%

Platform Release:
Blocks Release:
Backwards Incompatible:
No
Groomed:
No
Sprint Candidate:
No
Tags:
Documentation
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:
Sprint 52

Description

Background

In Pulp 2, workflows were defined by pulp platform, and modified by plugins. This restricted the freedom of plugin writers substantially, but enforced somewhat similar workflows for all plugins. This architecture allowed many of the plugin features to be documented generally by pulp platform, with specific portions (importer, distributor configs) needing to be documented by each plugin.

Currently

With Pulp 3, plugins are given features by the plugin API that work out of the box for many situations. This makes it tempting to document these features in pulpcore to avoid repetition. As an example, consider the upload workflow. Pulpcore provides the API to upload artifacts, and the plugins use the plugin API to implement content unit creation. Neither feature is useful without the other. Pulpcore can say some general things about content unit creation, but must be overly vague to account for various plugin workflows. The resultant docs are not as helpful, and cannot be improved very much without stating incorrect information about some plugins.

The plugins have compensated for this somewhat by providing detailed quickstart guides for each of the features. Personally, I frequently use plugin docs, and rarely use pulpcore docs as a user.

Proposal

This story is to add a section to the pulpcore docs entitled "How to use these docs".

This section will document for users, contributors, and plugin writers, what will be documented by pulpcore, and what will be documented by each plugin. All workflows will fall to the responsibility of each plugin. Pulpcore docs like artifact upload will remain in pulpcore in the reference guide. Plugin documentation will reference this to simplify their own "Upload workflow" documentation. The key shift is that the plugin documentation becomes the primary documentation for users.

Specific responsibilities (for user docs):

pulpcore:
  • High level explanations
  • Install guide
  • How to use these docs (including plugin docs)
  • core provided REST API calls
plugin:
  • workflows
    • (suggestion to plugins) bullet list of Workflows
    • sync (link to core for repository CRUD, repository version CRUD)
    • publish (link to core for distribution CRUD, publication CD)
    • upload (link to core for repository CRUD, artifact upload)
    • export

Specifically, this section should be renamed. https://docs.pulpproject.org/en/3.0/nightly/workflows/index.html
Nothing in here should be a complete workflow, instead, they will be generally useful components of plugin workflows. One idea for a name of this section is "General Core Features". Not a big fan, please suggest something better.


Related issues

Related to RPM Support - Task #4621: Add a bullet-list set of features that pulp_rpm supports and remove reliance/association with pulpcore MODIFIED Actions

Associated revisions

Revision 7e43d21d View on GitHub
Added by amacdona@redhat.com 6 months ago

Clarify responsibility for core and plugin docs

The audiences for this patch are users and plugin writers, each needing
to know how to approach the documentation since it is spread over
multiple repositories. Users of Pulp 2 are especially in need of this,
because the responsibility of documenting workflows have been moved to
the plugin docs.

https://pulp.plan.io/issues/4626

fixes #4626

History

#1 Updated by amacdona@redhat.com 7 months ago

  • Tags Documentation, Pulp 3 added

#2 Updated by amacdona@redhat.com 7 months ago

  • Description updated (diff)

#3 Updated by amacdona@redhat.com 7 months ago

  • Related to Task #4621: Add a bullet-list set of features that pulp_rpm supports and remove reliance/association with pulpcore added

#4 Updated by ipanova@redhat.com 6 months ago

what about "Features provided by Core"

I like the idea of plugins responsibly documenting their workflows, especially if our target is to increase plugins number. Pulpcore docs will just not be able to keep track of everything and all the customizations, so documenting generic features in pulpcore and linking them in plugins makes sense to me.

#5 Updated by amacdona@redhat.com 6 months ago

  • Status changed from NEW to ASSIGNED

#6 Updated by amacdona@redhat.com 6 months ago

  • Assignee set to amacdona@redhat.com

#7 Updated by amacdona@redhat.com 6 months ago

  • Status changed from ASSIGNED to POST

#8 Updated by amacdona@redhat.com 6 months ago

  • Status changed from POST to MODIFIED
  • % Done changed from 0 to 100

#9 Updated by daviddavis 6 months ago

  • Sprint/Milestone set to 3.0

#10 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

#11 Updated by amacdona@redhat.com 6 months ago

  • Sprint set to Sprint 52

Please register to edit this issue

Also available in: Atom PDF