Shields: waffle.io support

[marceloboeira]

[Potherca]

That would be awesome!

Especially when using the flat style, the waffle.io button sticks out like a sore thumb amongst all of the other nice shield.io buttons :smile:

[marceloboeira]

@potherca yeap :3

[espadrine]

@potherca Can you point me to an example? It'd help me start off.

[Potherca]

Sure. I use Waffle.io for a project of mine, I'll use that for this example.

In its most simple form the badge from Waffle is in the form of

https://badge.waffle.io/[VENDOR]/[PROJECT].png

So for my project that would be https://badge.waffle.io/potherca/GraphvizWebEditor.png, which results in:

However, there are a few caveats...

By default Waffle.io adds a "ready" label to your github issues. If you change that/use another label, this also needs to be changed for the badge label:

https://badge.waffle.io/potherca/GraphvizWebEditor.png?label=waffle:%20ready%20for%20development

It will also allow you to change the title:

https://badge.waffle.io/potherca/GraphvizWebEditor.png?label=waffle:%20ready%20for%20development&title=Issues%20ready%20for%20development

I'm unsure if you'd want to support these as the whole deal with the label feels like an implementation error on their side (the application _should_ be able to get the right label without me telling it which one that is) and the changing the title goes against the "one true form" principle that Shields.io also goes for.

That said, I hope this sets you up with a good example, let me know if anything is missing.

[waldyrious]

+1 for this as well.

[espadrine]

@potherca The badges you show are from my own design. The fact that they allow the user to pick the label, which shields.io provides (through, you guessed it, ?label=Issues ready for development), means they probably send a request to us dynamically.

There is no obvious Waffle.io API I can request data from, based on my light googling. However, the poor man's last resort is SVG scraping. I'd rather not do that, as it is very brittle.

[espadrine]

Further research yields this gem:

$ curl 'https://waffle.io/potherca/GraphvizWebEditor/columns'

[
  {
    "_id": "53dbac8f2b24740200536f63",
    "displayName": "Backlog",
    "isBacklog": true,
    "isDone": false,
    "rank": 0,
    "fullName": "potherca/graphvizwebeditor",
    "columnDescriptionHeader": "Backlog Column",
    "columnDescriptionBody": "Any open issues automatically show up in this column.",
    "nonCollaboratorPrStart": false,
    "collaboratorPrStart": false,
    "project": "53dbac8f2b24740200536f61",
    "__v": 0,
    "inProgressStart": false,
    "issues": [
      {
        "rank": 0,
        "id": 26735412
      }
    ]
  },
  {
    "_id": "53dbac8f2b24740200536f65",
    "displayName": "In Progress",
    "isBacklog": false,
    "isDone": false,
    "label": {
      "color": "eac04b",
      "name": "waffle: in progress"
    },
    "rank": 2,
    "fullName": "potherca/graphvizwebeditor",
    "columnDescriptionHeader": "In Progress Column",
    "columnDescriptionBody": "Let others know you're working on an issue by dragging it to In Progress.",
    "nonCollaboratorPrStart": true,
    "collaboratorPrStart": true,
    "project": "53dbac8f2b24740200536f61",
    "__v": 0,
    "inProgressStart": true,
    "issues": [
      {
        "id": 27714584,
        "rank": 0
      }
    ]
  },
  {
    "_id": "53dbac8f2b24740200536f66",
    "displayName": "Done",
    "isBacklog": false,
    "isDone": true,
    "rank": 3,
    "fullName": "potherca/graphvizwebeditor",
    "columnDescriptionHeader": "Done Column",
    "columnDescriptionBody": "Issues closed in the last week are shown in this column. Drag issues here to close them.",
    "nonCollaboratorPrStart": false,
    "collaboratorPrStart": false,
    "project": "53dbac8f2b24740200536f61",
    "__v": 0,
    "inProgressStart": false,
    "issues": []
  },
  {
    "_id": "53dbac8f2b24740200536f64",
    "displayName": "Ready",
    "isBacklog": false,
    "isDone": false,
    "label": {
      "name": "waffle: ready for development",
      "color": "00c5fe"
    },
    "rank": 1,
    "fullName": "potherca/graphvizwebeditor",
    "columnDescriptionHeader": "Ready Column",
    "columnDescriptionBody": "Place issues in this column when they are ready to be worked on.",
    "nonCollaboratorPrStart": false,
    "collaboratorPrStart": false,
    "project": "53dbac8f2b24740200536f61",
    "__v": 0,
    "inProgressStart": false,
    "issues": [
      {
        "rank": 0,
        "id": 39298137
      },
      {
        "rank": 1,
        "id": 39206153
      },
      {
        "rank": 2,
        "id": 26735488
      },
      {
        "rank": 3,
        "id": 26735460
      },
      {
        "rank": 4,
        "id": 27705232
      },
      {
        "rank": 5,
        "id": 39302367
      },
      {
        "rank": 6,
        "id": 27712254
      },
      {
        "rank": 7,
        "id": 26735447
      }
    ]
  }
]

However, this is not really officially public. It looks like they will eventually move it under /api/. I therefore asked for an ETA.

[espadrine]

Bummer. There's only 8 issues listed under "waffle: ready for development", and the badge shows 9.

[balupton]

+1

[csMACnz]

+1

[hairyhenderson]

+1

While not really relevant to this issue, just want to mention that it looks like SVGs badges are supported by waffle.io too: i.e.
https://badge.waffle.io/potherca/GraphvizWebEditor.svg?label=waffle:%20ready%20for%20development

This at least makes the badge a bit prettier when using retina displays etc.

...actually, after a bit of digging it looks like _all_ badges served by badge.waffle.io are actually SVGs, even when I request a .png URL. (this is weird, right?)

[marceloboeira]

@hairyhenderson nice tip :+1:

[espadrine]

...actually, after a bit of digging it looks like all badges served by badge.waffle.io are actually SVGs, even when I request a .png URL. (this is weird, right?)

It is something we recommend. The file extension is ignored by browsers. The major thing they look at is the HTTP header which sets the content type. As a result, that trick allows all users to switch to the better image without requiring all of them to edit their URLs.

[zbeekman]

+1

[raineorshine]

Would love the flat design for this badge :+1:

[marceloboeira]

@metaraine yeap!

[duckinator]

What's the status on this, and is there anything I can do to help out with it?

[ELLIOTTCABLE]

:+1: (also: ohai, @duckinator)

It _should_ be easy, according to this comment, it doesn't even depend on Waffle.io exporting any API! Their own badges use the GitHub API, not theirs.

[Kubuxu]

:+1:

[koistya]

:+1: missing the flat style.

[ghost]

:+1:

[nwalters512]

Any updates on this? Would love to see the flat style in use.

[espadrine]

Waffle's API was finalized last week: https://github.com/waffleio/waffle.io/issues/468.

curl 'https://api.waffle.io/potherca/GraphvizWebEditor/columns'

List of objects (one per column) with those relevant fields:

• displayName: name to use by default on the left.
• issues: list of issues; count them and put that figure on the right of the badge.
• label.name: name to filter with.
• label.color: color to use if set.

Proposed shields URL:

• /waffle/column/potherca/GraphvizWebEditor.svg shows the number of ready issues.
• /waffle/column/potherca/GraphvizWebEditor/in progress.svg shows the number of in progress issues.

Any objection to that design?

[hairyhenderson]

@espadrine - maybe missing something, but why would column be part of the path?

Why not just /waffle/potherca/GraphvizWebEditor.svg?

[caalberts]

flat design :+1:

[lots0logs]

:+1:

[espadrine]

Why not just /waffle/potherca/GraphvizWebEditor.svg?

We've had tons of issues in the past with vendors that offered more than one product, and suddenly we had a /vendor/ path and a /vendor/product/ path for every other thing. It's easier and more intuitive to start off with the second form.

[hairyhenderson]

@espadrine - :+1: that makes sense.

[astrojuanlu]

:+1: and subscribing :)

[klarkc]

+1 and subscribing

[nelson6e65]

:+1:

[espadrine]

This is not yet featured on the front page. It would be great if you could check that the implementation works. Here are two examples:

https://img.shields.io/waffle/column/potherca/GraphvizWebEditor.svg
https://img.shields.io/waffle/column/potherca/GraphvizWebEditor/waffle:%20in%20progress.svg

[evancohen]

Hey @espadrine, thanks for this!

I'm having an issue with this badge, it should show 1 item in progress (at the time of this writing), but it shows none...

https://img.shields.io/waffle/column/evancohen/smart-mirror/in%20progress.svg

VS
https://badge.waffle.io/evancohen/smart-mirror.svg?label=in%20progress&title=In%20Progress

I was a bit confused so I took a look at the API you described above:

curl 'https://api.waffle.io/evcohen/smart-mirror/columns'

It appears that I am missing the issues field in the API response, which is why this will always result in 0 for any tag that I try to use.

Looks like @klarkc has a similar issue (although the issues array exists in his curl response it's always empty):
https://img.shields.io/waffle/column/klarkc/gulp-github-automator.svg

This should be 10, but it's 0.

[espadrine]

@evancohen Thanks for detailing that issue! There's definitely something strange happening. For starters, while https://api.waffle.io/evcohen/smart-mirror/columns does not provide the issues field, https://api.waffle.io/evancohen/smart-mirror/columns does, but it is empty where it should contain an issue.

Here is an issue I raised on the subject: https://github.com/waffleio/waffle.io/issues/2466. I'd expect this API to be more resilient (and faster, assuming caching) in the future.

In the meantime, I will try to extend the GitHub issues badge to support label querying, which will look something like this: https://img.shields.io/github/issues-raw/evancohen/smart-mirror/in%20progress.svg. Unfortunately, obtaining the color and display name would require two GitHub requests in the general case, so that won't happen.

[nelson6e65]

Hmm... I was trying to use label title (In%20Progress), but did not work:
https://img.shields.io/waffle/label/nelson6e65/php_nml/In%20Progress.svg

• Shield:
• Original:

Then, I used github label instead (Because I changed to use wip instead of default):
https://img.shields.io/waffle/label/nelson6e65/php_nml/wip.svg

It should be documented that format is
https://img.shields.io/waffle/label/{user}/{repo}/{github_label}.svg
instead of
https://img.shields.io/waffle/label/{user}/{repo}/{waffle_label}.svg.

I was a little bit confused. :sweat_smile: