Story #4626
Updated by amacdona@redhat.com about 5 years ago
h2. 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.
h2. 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.
h2. 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.
h2. 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.
.