Add documentation for designing badge URLs (badges#4435)

* Add documentation for designing badge URLs
Co-authored-by: Caleb Cartwright <[email protected]>

CONTRIBUTING.md

@@ -104,12 +104,8 @@ There are three places to get help:
 
 ## Badge URLs
 
-- The format of new badges should be of the form
-  `/SERVICE/NOUN/PARAMETERS/QUALIFIERS`. For instance,
-  `/gitter/room/nwjs/nw.js`. The vendor is gitter, the
-  badge is for rooms, and the parameter is nwjs/nw.js.
-- Services which require a url/hostname parameter should use a query parameter to accept that value. For instance,
-  `/discourse/topics?server=https://meta.discourse.org`.
+- The format of new badges should be of the form `/SERVICE/NOUN/PARAMETERS`.
+- There is further documentation on this in [badge-urls](https://github.com/badges/shields/blob/master/doc/badge-urls.md)
 
 ## Coding guidelines
 

doc/TUTORIAL.md

@@ -151,6 +151,7 @@ Description of the code:
      number of named parameters. These are converted into
      regular expressions by [`path-to-regexp`][path-to-regexp].
      Because a service instance won't be created until it's time to handle a request, the route and other metadata must be obtained by examining the classes themselves. [That's why they're marked `static`.][static]
+   - There is additional documentation on conventions for [designing badge URLs](badge-urls)
 6. All badges must implement the `async handle()` function that receives parameters to render the badge. Parameters of `handle()` will match the name defined in `route()` Because we're capturing a single variable called `text` our function signature is `async handle({ text })`. `async` is needed to let JavaScript do other things while we are waiting for result from external API. Although in this simple case, we don't make any external calls. Our `handle()` function should return an object with 3 properties:
    - `label`: the text on the left side of the badge
    - `message`: the text on the right side of the badge - here we are passing through the parameter we captured in the route regex

doc/badge-urls.md

@@ -0,0 +1,26 @@
+# Badge URL Conventions
+
+- The format of new badges should be of the form `/SERVICE/NOUN/PARAMETERS?QUERYSTRING` e.g:
+  `/github/issues/:user/:repo`. The service is github, the
+  badge is for issues, and the parameters are `:user/:repo`.
+- Parameters should always be part of the route if they are required to display a badge e.g: `:packageName`.
+- Common optional params like, `:branch` or `:tag` should also be passed as part of the route.
+- Query string parameters should be used when:
+  - The parameter is related to formatting. e.g: `/appveyor/tests/:user/:repo?compact_message`.
+  - The parameter is for an uncommon optional attribute, like an alternate registry URL.
+  - The parameter triggers application of alternative logic, like version semantics. e.g: `/github/v/tag/:user/:repo?sort=semver`.
+  - Services which require a url/hostname parameter always should use a query string parameter to accept that value. e.g: `/discourse/topics?server=https://meta.discourse.org`.
+
+It is convention to use the following standard routes and abbreviations across services:
+
+- Coverage: `/coverage`
+- Downloads or Installs:
+  - Total: `/dt` - Use this even for services that only provide the total download/install data
+  - Per month: `/dm`
+  - Per week: `/dw`
+  - Per day: `/dd`
+- Rating:
+  - Numeric: `/rating`
+  - Stars: `/stars`
+- License: `/l`
+- Version or Release: `/v`