Document how to change the categories in the README & toml

Author: carols10cents

README.md

@@ -123,6 +123,21 @@ follows:
     ```
     cargo test
     ```
+    
+## Categories
+
+The list of categories available on crates.io is stored in
+`src/categories.toml`. To propose adding, removing, or changing a category,
+send a pull request making the appropriate change to that file as noted in the
+comment at the top of the file. Please add a description that will help others
+to know what crates are in that category.
+
+For new categories, it's helpful to note in your PR description examples of
+crates that would fit in that category, and describe what distinguishes the new
+category from existing categories.
+
+After your PR is accepted, the next time that crates.io is deployed the
+categories will be synced from this file.
 
 ## Deploying & Using a Mirror
 

src/categories.toml

@@ -1,3 +1,31 @@
+# This is where the categories available on crates.io are defined. To propose
+# a change to the categories, send a pull request with your change made to this
+# file.
+#
+# For help with TOML, see: https://github.com/toml-lang/toml
+#
+# Format:
+#
+# ```toml
+# [slug]
+# name = "Display name"
+# description = "Give an idea of the crates that belong in this category."
+#
+#  [slug.categories.subcategory-slug]
+#  name = "Subcategory display name, not including parent category display name"
+#  description = "Give an idea of the crates that belong in this subcategory."
+# ```
+#
+# Notes:
+# - Slugs are the primary identifier. If you make a change to a category's slug,
+#   crates that have been published with that slug will need to be updated to
+#   use the new slug in order to stay in that category. If you only change
+#   names and descriptions, those attributes CAN be updated without affecting
+#   crates in that category.
+# - Slugs are used in the path of URLs, so they should not contain spaces, `/`,
+#   `@`, `:`, or `.`. They should be all lowercase.
+#
+
 [development-tools]
 name = "Development Tools"
 description = "Ways to make developing in Rust better"