Totally forgot to mention it but I've wanted a "version:x.y.z" tag for a while so we could flag and filter on when specific features came in.

Moved to draft for now - this isn't included in a TOC, so breaks the doc build.

I think a domain: signal processing should be suitable (even if mlab and many of the related functions are removed).

Not clear if element: text should be added as there are several related, but worth considering.

element: axis may have a role considering how often we talk about them in the documentation.

aesthetic: layout?

plot type: 3d (which is pretty wide, but probably still an interesting subset)

Is there another word for aesthetic? I think I will learn to spell it, but I guess I'm not the only one that will get it wrong a few times... (Not that I object the word as such... But "styling"?)

I think it's a really solid proposal! Thank you Eva for doing this work!

My thoughts:

• component:
  • are the component tags used strictly to tag the MPL components, or the functional components? e.g. if I have an example where a plot has a title and a subtitle created not with ax.set_title, but with ax.annotation, will it be tagged as component:title?
  • related to this, would it make sense to create some kind of dictionary between the MPL lingo and the most common dataviz concepts, used by designers/scientists etc., e.g. I am not sure if many people who need to use MPL for their work know immediately what a "spine" is, especially if they use English as a second language - or in other words, how might we also make the tags friendly and useful for those users?
  • thinking about examples of layouting, does it make sense to use something like component:layout that would involve various examples of plt.subplots(), plt.subplot_mosaic() etc. instead of component:subplot
  • I feel the tags should be defined in such a way that doesn't duplicate the text search functionality
  • especially for components like axes there needs to be a clear rule which examples containing axes (virtually all of them...) should be tagged and which should be left out, e.g. since when an example becomes "taggable"
• plot type:
  • which plot types should be tagged and which not? how to decide?
  • which plot type names should we take, should they be coupled to one particular existing dataviz catalogue or standard? e.g. would a dumbbell plot be tagged as a dumbbell plot, or as cleveland dot plot, or both?
  • if we have an example showing a complex plot type composed out of the MPL primitive plots e.g. a dumbbell chart built out of ax.scatter and ax.plot, would this be tagged as plot type: scatter and plot type: plot, because it involves those two functions, or as plot type: dumbbell? do we want a distinction plot type: composed, plot type: in-built etc.?
  • there should be a clear rule on what goes into domain and what into plot type, e.g. for geovisualizations or more specialized charts like Lissajous curves that exist mostly in a particular domain context, but are a specific plot type, or plotting functions like .quiver
• interactivity
  • is this tag also meant to cover examples of interactivity with Jupyter widgets or SVG interactivity?
• aesthetic
  • it would be very helpful to have tags for data storytelling concepts like "custom subtitles", "fancy legends", "highlighting" - do they also fall in this category?
  • does aesthetic:size mean size of the chart, size of various elements, size of markers? or all at once? does it need to be more specific to be useful?
• other
  • it would be very useful to have tags for examples that demonstrate transformations, backends, animations or purely MPL concepts etc., but I'm not sure where they fit in the proposed classification

@paniterka So many good points, thank you! This is a long response, but I found it helpful to type up my thoughts so may as well make the discussion public.

re: components

• This is one of the questions to be worked out about whether tags refer to how the plots look or how they are made. Our conversations have erred on the side of how they look, since that seems more likely how users navigate the gallery. So, “component” here means “which piece of the chart are we talking about?” If it’s a good example of a title, it should be tagged “component: title” so that someone looking for inspiration on how to make titles will see it.

• Some of the MPL lingo vs. common dataviz concepts will hopefully be addressed by the “use case” column in the tag glossary, which gives a place to explain what a tag means/ how it should be used. Re: spine… this is simply confusing and I think @story645 had a good suggestion to reference the Anatomy of a Figure page for a visual cue of what the different components are. I agree that the language for tagging should definitely aim for simplicity! I already appreciated the suggestion to switch aesthetic to styling and save us all some headaches lol

• Re: component: layout — I have styling: small multiples but maybe that’s not a common enough way to refer to it? (We can include alternative phrasing in tag glossary “use case” column to cover multiple bases, but should always try to stick to one tag per concept)

• I think duplicating other forms of search is okay??

re: plot type

• Some guidelines that occur to me:
  • For redundant plot types, we should go with the more common usage, if it’s possible to determine. Any alternative names can be noted in the “use case” column next to the tag
  • Not every single plot type should have its own tag. If there’s only one or two examples of a plot type, users will be able to find them using regular search. The use case for tagging is more like “I want to compare different approaches to making a scatterplot” or “I want to see all the ways people have used linestyle in line charts”
  • I think a catchall specialty plot tag is, while subjective, helpful for reducing noise and keeping the other plot type subcategories manageable. If a plot type has only 1-2 examples or is clearly very specific to one domain, it can be tagged specialty plot (and/or given a relevant domain tag) rather than getting its own tag category.
• I love the idea of a distinction between plot type: composed and plot type: in-built. To me, in-built seems like the default, and I’d recommend only tagging plot type: composed (or plot type: combined or something else) because it seems more likely that someone will search for composed plots in that way, and search for in-built plots by name e.g. plot type: bar.

re: interactivity

• I know little about this aspect of MPL! I’ll do more research but welcome opinions/suggestions on the best way to tag this.

re: aesthetic

• Great idea. Perhaps a styling: visual design tag? I wonder how many different examples we have — if we need to have differentiated tags for "custom subtitles", "fancy legends", and "highlighting”, or if they could all fall under one tag.
• size is honestly a poor tag.. I will likely remove it!

Oh there is one action left for the docs build to work: you need to rebase/merge the main branch into yours, because of the switch to meson builds.

So here are the steps you need to take:

• git checkout main -> move to the matplotlib main branch
• git pull upstream main -> assuming your upstream is configured, this will pull the latest modifications in the upstream main branch
• git checkout tag-guidelines
• git rebase upstream/main -> this will put all your commits on top of the newest main changes. You should not see any conflicts as far as I'm aware, but if you want to make this easier you can squash your commits before doing this (https://matplotlib.org/devdocs/devel/development_workflow.html#rewrite-commit-history)

After this, push back into this branch with git push origin tag-guidelines and the docs build should work.

• Guidelines page
• Tags glossary

So summary on what we've discussed as process for proposing new tags. The rational for doing this as an issue first then PR is so maintainers don't try to review a PR adding tags w/o there first being consensus on the tags.

1. Open issue: do we want something like [Doc] new tag: tag name or does that get too prescriptive

2. explain rational for new tag

3. identify n (5, 10?) examples that would be tagged w/ the new tag

4. once there's consensus on accepting a tag (2? maintainers + no objections, @esibinga as tiebreaker for now):

   1. open pull request that adds tag to tag listing page w/ short rational if needed
   2. add tags to examples proposed in issue

@esibinga suggested this be a (possibly informal) template and I very much encourage/support codifying the tag proposal procedure as an issue template to help streamline proposal/discussion.

We'll do follow ups later today