A plea to reduce divergence from the npe2 manifest, and consult with napari devs, as much as possible

[tlambert03]

In reviewing https://github.com/chanzuckerberg/napari-hub/wiki/A-plugin-developer%E2%80%99s-guide-to-categories-on-the-napari-hub, I see now that the hub has now introduced it's own categorization schema for plugins.

This issue is a plea to the CZI team to make every attempt possible to reduce the number of places that a plugin developer needs to "be aware of" in order to have and modify their plugin's presence in the ecosystem.

We did originally have a field for categories in the manifest, but it was removed in napari/npe2#38. I know @neuromusic and @nclack and I all had some discussions in the plugin meetings about categories, but I can't remember the details now about why it was removed. In any case, I definitely would have wanted for those things to go in the manifest. If you'll recall my whole motivation for proposing the manifest was to be able to provide a richer in-app experience for users. And this type of metadata would definitely be useful. I had originally added categories to mimic the categories key in the vscode extension API.

Yes, napari could conceivably now hit the hub API to retrieve this information, but that seems more like an unfortunate workaround, and something that could be entirely avoided if we encourage plugins to put this in their manifest in the first place, rather than in a separate place. It also adds to the burden on plugin developers to remember all the places to add stuff.

I do like the EDAM categorization. It's clear you've put a lot of thought into. But I would greatly greatly (can't emphasize this enough) appreciate it if the napari core dev team, and specifically those developing the npe2 platform, could be looped in about these sorts of decisions that affect the plugin developer's experience. In this case, I would love it if we could go back to having categories in the manifest.

Thanks for your consideration/attention to this

cc @sofroniewn @jni @neuromusic @napari/core-devs

[tlambert03]

i think as a simple heuristic, I would propose this: If a change/proposal being considered by the CZI/hub team impacts the actions or API that a napari plugin developer (or the napari program) is expected to perform or use, then that should be a broader discussion with the napari team. If it's an improvement or modification to the way that the hub collects, organizes, or presents existing community data, but does not introduce new procedures that the napari project and/or plugin developers need to use, then that's internal "hub business", and no discussion with the community should be expected.

[tlambert03]

Linking @neuromusic comment #627 (reply in thread)

If you're not ready to commit to this heuristic, this would be a good place to explain why

[neuromusic]

@sofroniewn tried to capture this in the comment below: #447 (comment)

[jni]

I'm supportive of this. To be honest I don't remember whether I was involved in discussions about the categories idea. If so, I'm sorry that I didn't flag them for inclusion with npe2. We already had the .napari folder (which predates npe2) so I can see how that seems like a sensible place to add stuff, but I agree that a single file to edit is preferable, and that categories would fit in npe2.

I also like Talley's proposed heuristic above.

[DragaDoncila]

I too am supportive of having the npe2 manifest as a single source of truth for plugin information that is shared (or will be shared) across napari hub and napari app interfaces. Not only does this reduce maintenance load for plugin developers, but it's likely to make display in napari itself easier and faster. I think this extends to the plugin categories, as long as we maintain existing behavior for plugins already using config.yml.

More broadly I feel that hub features should be developed "napari first" rather than "napari hub first". Wherever possible we should strive to either surface information already provided by plugin developers through existing sources (whether this be documentation, standard package files or the npe2 manifest), or try to add new information to these existing sources. As an example, despite being a proponent of the DESCRIPTION.md file - because I do think it's valuable for developers to provide a condensed, succinct description that can be shown outside of their main documentation - I've been annoyed at having to maintain two sources of documentation (or three if the README is separate from the main body of docs). I would much prefer the hub offering me a way to point to an existing markdown file, or using MyST/Sphinx style include directives to piece together a description from existing documentation.

[neuromusic]

Thank you for raising your concerns, Talley.

I value our partnership with the napari team and it’s important to me personally that we can work effectively together to support napari’s users and plugin developers. As with all of our work on the napari hub, we’ve strived from the earliest phases of exploring the problem space, scoping and planning the solution, and launching the feature, to deeply understand the needs of napari’s users and we consider napari’s steering council and core developers key stakeholders in our work.

You raised a number of issues here so at the risk of being overly verbose, I’m going to try to address the major ones.

In reviewing https://github.com/chanzuckerberg/napari-hub/wiki/A-plugin-developer%E2%80%99s-guide-to-categories-on-the-napari-hub, I see now that the hub has now introduced it's own categorization schema for plugins.

I have to confess that I’m super confused by the surprise that you express at the launch of this feature and its reliance on .napari/config.yml, given that we’ve stated this was a priority for 2021 since the launch of the napari hub and the various conversations we’ve have had about this feature over the past 9 months. Moreover, back in December, in preparation for the launch, I personally opened a PR onto one of your plugins describing this feature, proposing categories for it in the .napari/config.yml file, and a link to the exact page that you reference above.

I would greatly greatly (can't emphasize this enough) appreciate it if the napari core dev team, and specifically those developing the npe2 platform, could be looped in about these sorts of decisions that affect the plugin developer's experience.

I’m happy to explore ways we can improve communication and coordination between our teams, but I strongly disagree with the notion that the napari hub team went rogue and failed to loop in the napari core dev team before launching this feature.

During the many months that the napari hub team was planning, building and rolling out this feature, we had a variety of conversations with you, other leaders in the napari community, and plugin developers about our goals here and our intent to let plugin developers specify categories through the .napari/config.yml file. @potating-potato led the implementation of backend support for ingesting these categories from .napari/config.yml and @DragaDoncila worked with @chili-chiu and myself to open 43 PRs onto plugin developer repo, recommending categories for their .napari/config.yml, the vast majority of which have been merged.

Throughout this entire process, I cannot recall any objections raised to adding categories to .napari/config.yml or a proposal of the npe2 manifest file as an alternative place for plugin developers to specify them. You say “I definitely would have wanted for those things to go in the manifest” but the only opposition I ever heard from you was your more general objection to the napari hub’s already-existing support for the .napari folder. I admit that I did not anticipate that adding support for additional fields would be a concern from you or any of the other core developers and I’ll own that mistake.

The heuristic you propose aligns well with the de facto way that we've tried to approach our work and our relationship with napari’s leadership, but I recognize that I could have done a better job at soliciting feedback on our specific plans & I can commit to our team being more diligent in the future in consulting with the napari core devs on plans that may impact plugin developers.

This issue is a plea to the CZI team to make every attempt possible to reduce the number of places that a plugin developer needs to "be aware of" in order to have and modify their plugin's presence in the ecosystem.

I understand that you would prefer to get rid of the .napari folder entirely, as you’ve expressed this more than once and I’ve shared our justifications more than once. As I’ve noted, we support this file as a mechanism for plugin developers to provide custom metadata for their napari hub listing so that they aren’t locked-in to only showing PyPI metadata, which may not always reflect what they want to display for napari users (versus the broader Python and open source software communities). Moreover, this file lets plugin developers easily opt-out of displaying their plugin on the napari hub without affecting PyPI distribution (and without needing to create an account or go through a review process) which was one of the very first features requested by a plugin developer.

If napari has features planned that would take advantage of categories or any other metadata we pull from .napari/ and there’s an opportunity to converge (as we intend to do with #237 now that the manifest file supports display_name), our team can revisit where we source such metadata from, what takes precedence, and what we might be able to deprecate. Please let me know when there’s a relevant issue or roadmap that I can follow (or if I missed it in my search), as I’d be eager for our team to work with you toward convergence where it makes sense.

[jni]

Thanks for your post @neuromusic!

the only opposition I ever heard from you was your more general objection to the napari hub’s already-existing support for the .napari folder. I admit that I did not anticipate that adding support for additional fields would be a concern from you or any of the other core developers and I’ll own that mistake.

Yeah I think this is where communication got muddled, and from @tlambert03's perspective the issue is that anything that gets added to .napari/ makes it harder again to deprecate in favour of the npe2 manifest.

I'll reiterate that I actually didn't have @tlambert03's concerns on my radar, so I didn't blink about the categories PRs that came to my plugins. Indeed I appreciated them and have told @neuromusic as much. Ultimately, I'm sure getting mixed messages from the community like this does not make your job easier @neuromusic!

I think going forward, we need to be more careful to adhere to the decision making process outlined in our governance doc:

napari uses a “consensus seeking” process for making decisions. The group tries to find a resolution that has no open objections among core developers. Core developers are expected to distinguish between fundamental objections to a proposal and minor perceived flaws that they can live with, and not hold up the decision-making process for the latter. If no option can be found without objections, the decision is escalated to the SC, which will itself use consensus seeking to come to a resolution. In the unlikely event that there is still a deadlock, the proposal will move forward if it has the support of a simple majority of the SC.

In this case, I think the "no open objections" element was missed, but at the same time, I'm not sure the distinction between "perceived flaws" and "fundamental objections" was clear. But we certainly should have done a better job of seeking out that clarification.

At any rate, we can now work together towards one of two options:

• rename .napari to .napari-hub, and make sure that only things that are very hub-specific live there. tbh I'm rather torn about "hide from hub listing" as a field in the npe2 manifest. However, if the setting also affects listing in the built-in plugin explorer, then I think it makes some sense in putting it in the manifest, even if the hub is actually serving that data.
• deprecate .napari in favour of the manifest. This one needs super careful consideration, because I would like the manifest to be as simple as possible. The use case of different support/home URLs, for example @neuromusic, is one where I'd consider just not supporting in the future, in favour of setup.cfg, just to reduce cognitive load on plugin devs. Even if it came from a dev issue, there needs to be consideration not just of feature requests but of the burden those requests place on maintenance and future development. This is a very tricky balance so it's not at all surprising that we have disagreement. Either way, we should discuss it at a higher level.

I think either option requires a NAP-style (napari/napari#4299) proposal, which we should get off the ground soon.

[sofroniewn]

Thanks for weighing in here too @neuromusic and @jni.

I want to reiterate @neuromusic’s comment that on the CZI end we really do value our partnership with napari and appreciate the time and input we get from napari core developers while we are building the hub.

I do want to clarify though CZI and the napari steering council did agree before the hub was created that the hub would be developed by CZI as a service provided by CZI in collaboration with napari - which is why it lives as a repository in the CZI GitHub org and not the napari GitHub org, and is described as such on the hub about page. For this reason the hub doesn’t adhere strictly to the napari governance structure and processes outlined above, but obviously we want to be a healthy part of the napari community and work together with the napari core developer team in as best and collaborative way as possible. We can add something even more explicit about the hub governance to this repo to help further clarify our working model.

rename .napari to .napari-hub, and make sure that only things that are very hub-specific live there

I think if the napari team decides that it never wants to use the .napari/ folder then this option makes a lot of sense. The hub is an opt-in service to plugin developers provided by a 3rd party (CZI) and it is very common in these situations to have service specific configurations. Again we obviously want to coordinate with the napari team on what those configurations are and reduce any duplication with information already provided in other places. Making the plugin development experience a light-weight and easy process is a large goal of ours and a reason we’re engaged heavily in user research around choices like this with the plugin developer community.

Overall though, I’m very optimistic about the current situation. I can imagine scenarios where the hub team adds something to the hub configuration that napari thinks is so important it wants in the manifest and I can imagine scenarios where the napari team adds something to the manifest that the hub team thinks is so important it wants it displayed in the hub. To me both of those are productive outcomes as long as migrations and deprecations are handled appropriately. Both napari and the napari hub are in an exciting growth phase now and I think it’s ok if a few mistakes happen along the way, as long as we keep working in a healthy collaboration.