Project

Profile

Help

Story #4626

closed

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 almost 5 years ago. Updated over 4 years ago.

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

100%

Estimated time:
Platform Release:
Groomed:
No
Sprint Candidate:
No
Tags:
Documentation
Sprint:
Sprint 52
Quarter:

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 pulpcoreCLOSED - CURRENTRELEASEbmbouter

Actions
Actions #1

Updated by amacdona@redhat.com almost 5 years ago

  • Tags Documentation, Pulp 3 added
Actions #2

Updated by amacdona@redhat.com almost 5 years ago

  • Description updated (diff)
Actions #3

Updated by amacdona@redhat.com almost 5 years ago

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

Updated by ipanova@redhat.com almost 5 years 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.

Actions #5

Updated by amacdona@redhat.com almost 5 years ago

  • Status changed from NEW to ASSIGNED
Actions #6

Updated by amacdona@redhat.com almost 5 years ago

  • Assignee set to amacdona@redhat.com
Actions #7

Updated by amacdona@redhat.com almost 5 years ago

  • Status changed from ASSIGNED to POST

Added by amacdona@redhat.com almost 5 years ago

Revision 7e43d21d | View on GitHub

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

Actions #8

Updated by amacdona@redhat.com almost 5 years ago

  • Status changed from POST to MODIFIED
  • % Done changed from 0 to 100
Actions #9

Updated by daviddavis almost 5 years ago

  • Sprint/Milestone set to 3.0.0
Actions #10

Updated by bmbouter almost 5 years ago

  • Tags deleted (Pulp 3)
Actions #11

Updated by amacdona@redhat.com almost 5 years ago

  • Sprint set to Sprint 52
Actions #12

Updated by bmbouter over 4 years ago

  • Status changed from MODIFIED to CLOSED - CURRENTRELEASE

Also available in: Atom PDF