Crates.io search improvements

[okaneco]

This came up while working on #166

These are the current keywords in the cargo manifest:

keywords = ["color", "colour", "space", "linear"]

Goal

Improve search of palette on crates.io

Issue

According to the documentation you can have up to 5 keywords. That said, crate discovery isn't great on the site with how it handles searching and separating exact matches, keywords, and categories. I've not had pleasant experiences trying to find things on there in the past or at least some type of "canonical" crate for a task.

Searching "palette" in the keywords, it doesn't come up but palette_derive does so that might be a good keyword to add: https://crates.io/keywords/palette. Others like like https://crates.io/keywords/space don't initially seem to be a good use of keyword because of how "dumb" the search is, however "colo[u]r space" brings up the crate as a top hit so keywords combine in your favor. I think it pulls some from the readme since searching for "srgb", palette and *_derive came up 2nd and 3rd, along with other crates being surfaced in similar color space/model searches.

Suggestions

Add at least one more keyword. I think "pixel" may be the best candidate over "palette", since the crate doesn't show up while searching it https://crates.io/search?q=pixel and that's very relevant to what a lot of us want to do. Ideally search wouldn't differentiate color/colour so "colour" is probably still worth a keyword instead of replacing it with "palette".

It might make more sense to include a sentence of all the color models that palette works with and a sentence of some features people might be looking for in the description so it'll get hits in the search. An example being if you search "hwb", palette doesn't appear in the results. palette generally does well showing up at the top for queries like "srgb". Whatever you think the most important features are that can fit in 2-3 sentences probably makes the most sense. In this research, I looked up "lab" and palette doesn't surface however two CIEDE2000 color difference crates do that I didn't know about (funny enough, they avoid the test case that gave us errors until we switched to f64).

These are some of the words that I think should be in the description based on lack of presence in searches:

• Alpha composition/alpha compositing
• Luma, luminance
• color difference, contrast ratio
• HSL, HSV, HWB, Lab, Lch (HCL), RGB, Xyz, Yxy

Motivation

I'm by no means an expert but this is inspired by not finding this crate until after seeing an announcement for version 0.5 came out and I'd already painfully reimplemented parts of this in my projects. Search never surfaced the crate despite doing things I was really interested in like the color handling and gradients. It can save a lot of headaches having a crate that does color so well and plays nicely with image which is probably going to be most new rust users' experience with manipulating pixels.

[Ogeon]

Good points throughout. I don't think I ever understood exactly how the keywords work, so I'm not surprised they are not optimal. And I don't know how it calculates relevance half the time. This may require multiple attempts, with releases in between, but let's start with:

• Updating the short description to something that better summarizes the feature.
• Changing the keywords to something more search friendly. "color" (and "colour"?) is a given, "pixel" is a good suggestion. "space" and "linear" may not be precise enough, so let's drop those in favor of something else. Maybe "gradient" and "blending", or "rgb"? I'm not sure.
• Adding a feature summary to the readme. If it's indeed indexed, that would be a great addition. It could also mention gradients and blending.
• Assigning the crate to the graphics category.

It may also be good to look around for some information regarding this. I haven't done it myself, yet.

[okaneco]

I haven't bundled a crate of my own yet but I've been meaning to. I'm checking out the book now, I never fully read this part before
https://doc.rust-lang.org/cargo/reference/publishing.html

I can't fathom the relevance calculation either. I got the results to recommend in my initial comment from typing in queries and checking results. The main search is https://crates.io/search?q= and the keywords are at https://crates.io/keywords. I think that's the main way users search? You can also do https://crates.io/categories.

1. Updating the short description to something that better summarizes the feature set.
2. Changing the keywords to something more search friendly

• "linear" actually surfaces palette in the top 5 results and top for "linear color" so I think it can stay or go.
• palette is already the 3rd result for gradient and first one that deals with color/image manipulation
• blending couldn't hurt, maybe something with convert/conversion/converter for searches in combination with color conver*. I think search the terms and see what the related crates
• I don't have any strong preferences, any addition is an improvement
• keywords = ["color", "conversion", "linear", "pixel", "rgb"]? I'm not sure how keywords and readme/descriptions are weighted

3. Adding feature summary to readme

• This would be great. I think it'd be good to put in the first section before ## Online Documentation so people can get the bullet points of the crate up front with minimal scrolling and agitation of not knowing what a project does in the first 30 seconds of reading about it. I didn't feel that way about this crate but I know it's a common complaint of anything tech today.
• I think you're right about needing multiple versions of experimentation to work it out. As for the readme, I found this. It can't hurt to lightly repeat some things in the description and readme in case the readme doesn't render (somtimes it errors out for me even though I've enabled docs.rs XHR scripts to load). https://doc.rust-lang.org/cargo/reference/manifest.html?#the-package-section

  # This points to a file under the package root (relative to this `Cargo.toml`).
  # The contents of this file are stored and indexed in the registry.
  # crates.io will render this file and place the result on the crate's page.
  

• Include gradients and blending/blend modes in the feature summary

4. Adding a categories field

• These seem the most suitable and can be combined
  • "graphics"
  • "multimedia::images" (multimedia -> subcategory: images)
  • "no-std"
• categories = ["graphics", "multimedia::images", "no-std"]

I'm learning a lot about this now but can't find a comprehensive "how to get your crate found on crates.io" article so we're in uncharted territory.

---

2019-02-19 edit

The following changes were made to the palette cargo.toml in #169

• [x] categories = ["graphics", "multimedia::images", "no-std"]
• [x] keywords = ["color", "conversion", "linear", "pixel", "rgb"]

[Ogeon]

I would guess most people go for the search input. It's very prominent and I would assume people are mostly used to using search by now.

keywords = ["color", "conversion", "linear", "pixel", "rgb"]

Probably better than what it has now, so let's try that.

Yes, the feature summary should be just under the general summary. The online documentation doesn't need all that space, so it can be moved and/or replaced with a badge. There's one for the released documentation, at least. This may also be a good argument for having separate readmes for the repo root and crates.io (they are currently symlinked), as the badges and documentation links are irrelevant on crates.io. The repo readme can be more general and mention contribution info, while the crates.io readme can have more focused information for library users.

categories = ["graphics", "multimedia::images", "no-std"]

Sure! I somehow got the impression that there could only be one category, but this is even better.

[mckingho]

Hi @Ogeon , this repo's latest version in crates.io is 0.5.0. It was released last year and there are a number of commits since then. May I know why it is not updating?

[Ogeon]

Hi! I have just been doing other things for a while (I do this on my free time, after all), so there are still a few outstanding changes before I think it's ready. The things I have in mind is primarily to update the readme files and some documentation, and also improve the naming for a few new parts.

That said, the development of this library is generally not fast moving, so don't expect frequent releases if there aren't any severe issues to fix. 🙂

But i agree it's about time I get it out there already, so I may get back to it this weekend.

[mckingho]

@Ogeon Thank you for your great work. I am curious because I am using a new function after latest release. But it is fine. I can import it from repository directly anyway.

[Ogeon]

I see, but nice that you are able to use the repo directly in the meantime. Feel free to open issues if you have any feedback on the changes. 🙂