Project

Profile

Help

Task #3772

Move plugin writers guide to template and refactor

Added by amacdona@redhat.com over 1 year 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:
Yes
Sprint Candidate:
No
Tags:
Documentation, Plugin Template
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:
Sprint 42

Description

The plugin template will house the bulk of the plugin writer docs.

Give plugin writers a base for documentation:

Completion of this task will create docs/template/ directories. Overviews and guides should be included in this directory, documentation of what to do with in specific areas of the code should be moved to comments in that code. When running bootstrap.py, docs/* should be included but not docs/template/. The Makefile should work for a bootstrapped plugin.

What should go where:

The index of the guide contains some generally useful information outlining what plugins do, this should stay in the pulpcore docs, possibly moved to Plugins index next to the plugin list.

Planning Guide should move to the plugin template docs. Suggest rename to "Overview"

Checklist should be moved to the template docs. It is probably worth separating the checklist into 2 sections. (1) Tasks done by the template and (2) Tasks done by a plugin writer. This way, the plugin writers who use the template will know what was done for them.

Writing Your First Plugin is the narratave documentation, and should be moved to the template. Suggest rename to "Plugin Writing Walkthrough".
  • The "Understanding Models" section be replaced with a link to pulpcore's docs/overview/concepts.rst. For concepts not mentioned in the core overview, they should be explained in the steps where they are relevant. For example, RemoteArtifact and PublishedArtifact should be added to the steps for implementing sync and publish.
  • Begin with assumed knowledge, at minimum including links to the planning guide and overview/index.rst
  • Move the bootstrapping instructions from plugin_template/README to a new section "bootstrapping"
  • The rest of the document becomes a TODO list for plugin writers. The specifics should be moved to the relevant modules. Add content for why a plugin writer might need to do this step. It may be possible to combine this with the checklist.
  • Pulp Plugin Basics should be combined with the planning guide/overview. "Documenting your API" should be moved to its own section.
  • Releasing your plugin should be moved to the plugin template, but does not need to be altered.
  • Generating a CLI is a stub, but should be moved to the template, and an issue filed to complete it.

Code modules:

The instructions should be moved into the modules, changing the code is not part of the scope of this task (unless it is incorrect.) Over time working code should be favored, because it can be tested (instructions can't). The comments should explain what the code does and include suggestions for expanding it.

History

#1 Updated by amacdona@redhat.com over 1 year ago

  • Description updated (diff)

#2 Updated by amacdona@redhat.com over 1 year ago

  • Sprint Candidate changed from No to Yes

#3 Updated by bmbouter over 1 year ago

I can see how this makes sense to do, but it will create some new challenges, specifically for how we render these docs online. For Pulp3 the current plan is to keep the docs builders really simple and not "combine" multiple sphinx projects or content from multiple repositories at build time the way we did in Pulp2.

How would this transition allow docs to be built and still keep the docs only building from 1 repository?

#4 Updated by amacdona@redhat.com over 1 year ago

@bmbouter, I don't think the plugin writers docs needs to live in the same place as the pulp docs. We could host on rtd, but I don't think its really necessary to host at all. For potential plugin writers gathering research, github rendered rst files will be enough, and anyone who is actually writing a plugin will have the template cloned locally. The plugin writer could be instructed to build the docs themselves or just use the files.

#5 Updated by bmbouter over 1 year ago

I see the docs living on one site as a big benefit. Splitting the docs across two sites seems like a step backwards. This change has benefits, but if that's the cost then I don't think it's something we should do.

The email advertising the changes did say the docs would move, but they also said it would leave high level docs in the existing repo and link to the plugin_template. I was focused on that second statement when I +1'd it, so I didn't think we were moving huge amounts of content.

I think the concern that our documentation would be leaving our docs site needs to be highlighted more clearly for everyone who +1'd this.

As an aside, I believe the plugin_template is not more useful than pulp_file and actually worse. I forked plugin_template into pulp_ansible, and I had to replace the name plugin_template in all the same places I would have replaced pulp_file. plugin_template was even less useful than pulp_file because in my case it was also out of date which caused me more time. pulp_file on the other hand is always up to date and we don't have to build additional things to help ensure that is true. We should really think hard if all this effort is (a) actually creating a better experience and (b) worth the cost it takes to maintain it.

I really think we should reconsider plugin_template entirely and delete it.

#6 Updated by bizhang over 1 year ago

I'm not convinced that pulp_file should serve as the de facto getting started guide.

The way I see it the plugin_template defines the minimum expectations for a generic plugin. pulp_file is simple and great but has things outside of this minimum set such as:
https://github.com/pulp/pulp_file/blob/master/pulp_file/manifest.py
https://github.com/pulp/pulp_file/blob/master/pulp_file/app/viewsets.py#L41
https://github.com/pulp/pulp_file/blob/master/pulp_file/app/models.py#L28

These are things necessary for the file_plugin to function, but are not needed for other plugins. My expectation for a bootstrapping template is that it should include only additive things, and not subtractive; I should not have to understand the pulp_file specific decisions in order to get started.

I think the best experience is an up to date plugin_template. I share the concerns over the complexity of keeping documentation in two different places and how to keep those documentation up to date. But I think in this case, my concerns are addressed with the promised plugin_template tests; if a change to the plugin API breaks the template, the person initiating that change has to make a PR to the plugin_template, and update the documentation along with that change. I think this process will keep our plugin writer's guide more up to date than the current way.

#7 Updated by amacdona@redhat.com over 1 year ago

@bmbouter, I want to point out that you don't have to do the renaming. `bootstrap.py` handles all of the grunt work, and new plugin writers start with a functional plugin. This is a huge advantage for new plugin writers, they only have to add things to something that already works. I had a very nice experience using the template to bootstrap docker 4.0. Everything just worked, and was very little effort.

It is difficult for new contributors to know the difference between what is required of all plugins and what the file plugin does. The exercise of stripping down the plugin would require knowledge of the file plugin, and I think it would waste a lot of plugin writer time.

Additionally, the comments in the file plugin are intended for file plugin developers, not plugin writers, and may not be very helpful. Plugin writers should be taught based on a simple example with comments that are intended for new plugin writers. The file plugin will still be an excellent resource, but isn't great for getting started.

I disagree that removing the plugin writer from pulpcore is a problem. None of the information is necessary for users, and will not likely be used by plugin maintainers either. Since it is a distinct use case, IMO there is no problem with separating it. In cases where the Plugin API changes and the template needs to be updated, we will already need PRs across repositories, so we aren't adding a new burden. And, as Bihan mentioned, in those cases the tests will fail. If we do want to host them, rtd is very easy and low maintenance.

I think this will not be a heavy maintenance burden, and will significantly lower the barrier to entry for plugin writers.

#8 Updated by dalley over 1 year ago

+1 to boostrap.py, +1 to using plugin_template as the reference and keeping it up to date.

#9 Updated by bmbouter over 1 year ago

These comments have convinced me that we should keep the plugin_template because:
  • bootstrap.py presents distinct value than pulp_file
  • the extra pulp_file specific things are not helping plugin writers for other content types

I'm +1 to groom then also because it probably will improve the plugin_template greatly and deleting plugin_template isn't an option.

Thank you for writing all of this out.

#10 Updated by dkliban@redhat.com over 1 year ago

  • Groomed changed from No to Yes

#11 Updated by rchan over 1 year ago

  • Sprint Candidate changed from Yes to No

#12 Updated by rchan over 1 year ago

  • Sprint set to Sprint 39

#13 Updated by amacdona@redhat.com over 1 year ago

  • Status changed from NEW to ASSIGNED
  • Assignee set to amacdona@redhat.com

#14 Updated by dkliban@redhat.com over 1 year ago

  • Sprint changed from Sprint 39 to Sprint 40

#15 Updated by rchan about 1 year ago

  • Sprint changed from Sprint 40 to Sprint 41

#16 Updated by rchan about 1 year ago

  • Sprint changed from Sprint 41 to Sprint 42

#17 Updated by dalley about 1 year ago

  • Status changed from ASSIGNED to MODIFIED

#18 Updated by werwty about 1 year ago

  • % Done changed from 0 to 100

Applied in changeset commit:d73ec31f75db6dfdebab8742982ea350cb0475a8.

#19 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

#20 Updated by bmbouter 6 months ago

  • Tags Plugin Template added

#21 Updated by bmbouter 6 months ago

  • Project changed from 27 to Pulp

The plugin template Redmine project is being consolidated into the Pulp Redmine project so all issues are being moved over.

#22 Updated by bmbouter 6 months ago

  • Sprint/Milestone set to 3.0

Please register to edit this issue

Also available in: Atom PDF