Pulp

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?

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.

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.

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.

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.

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

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.