Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Shields data format? #776

Closed
idleberg opened this issue Aug 23, 2016 · 8 comments · Fixed by #2397
Closed

Shields data format? #776

idleberg opened this issue Aug 23, 2016 · 8 comments · Fixed by #2397
Labels
core Server, BaseService, GitHub auth, Shared helpers

Comments

@idleberg
Copy link

For several years I've been maintaining snippets for a variety of text editors to easily insert badges. The update process has been proven painful, especially due to lack of versioning. I'm surprised I could not find any data-sets of all available badges, since I expected you would use that to generate content, for instance your website.

I would love to see is that you offer all available badges is some data-format, e.g. JSON or YAML. Ideally, these would include name, category and URL.

Example:

{
    "name": "Gratipay User",
    "url": "https://img.shields.io/gratipay/user/<% user %>.svg",
    "category": "Miscellaneous"
}

I think this data could be used for multiple purposes, including generating content such as your static website, which potentially makes maintenance easier and less error-prone. Let me know what you think, and I can submit a draft for review.
@idleberg idleberg changed the title Data format Shields data format? Aug 23, 2016
@paulmelnikow paulmelnikow added the question Support questions, usage questions, unconfirmed bugs, discussions, ideas label Apr 1, 2017
@paulmelnikow paulmelnikow added frontend The Docusaurus app serving the docs site developer-experience Dev tooling, test framework, and CI labels Apr 17, 2017
@paulmelnikow
Copy link
Member

Hi, thanks for this suggestion.

I love this idea. Would enable things like #701.

At the moment I'm focused on tests of the vendor badges (#927) and then, continuing to work through the backlog of PRs. We should keep it on the roadmap, though clearly it would be a pretty big endeavor…

@paulmelnikow paulmelnikow added enhancement and removed question Support questions, usage questions, unconfirmed bugs, discussions, ideas labels Apr 17, 2017
@paulmelnikow
Copy link
Member

Also related: #777, #466

@paulmelnikow paulmelnikow mentioned this issue Apr 18, 2017
Closed
@Daniel15 Daniel15 mentioned this issue Apr 19, 2017
Closed
@paulmelnikow paulmelnikow mentioned this issue May 2, 2017
Merged
@paulmelnikow paulmelnikow added core Server, BaseService, GitHub auth, Shared helpers frontend The Docusaurus app serving the docs site and removed frontend The Docusaurus app serving the docs site labels Oct 10, 2017
@paulmelnikow
Copy link
Member

#1163 implements a rough version of this. It's not formalized, nor guaranteed to stay the same, though it's a great step in the right direction.

@paulmelnikow paulmelnikow mentioned this issue Oct 12, 2017
Merged
7 tasks
@paulmelnikow paulmelnikow removed developer-experience Dev tooling, test framework, and CI frontend The Docusaurus app serving the docs site labels Oct 12, 2017
@paulmelnikow paulmelnikow mentioned this issue Oct 30, 2017
Closed
@paulmelnikow
Copy link
Member

@idleberg See #1226 and mightyiam/shields-badges-urls#22 about a project related to badge URL generation.

In that thread I suggested we kickstart this issue, our publishing a data format. It's going to be a while before we have the kind of comprehensive data I'd like for all the badges, though we could certainly start with what we have. I'm curious your thoughts on the ideal content for that data format, and also the minimum useful content.

You might also have some really valuable input for him, as I'm sure you've needed to solve some of the same problems as he's thinking through right now.

@mightyiam
Copy link

I think that https://github.com/mightyiam/shields-badges-urls aims to provide what you intend to consume, @idleberg, but it is a JavaScript (TypeScript) API, rather than data. The nature of it includes string composition, so it did not occur to me to make it a data format, rather than code. But if simple rules are followed, perhaps the string compositions could be encapsulated in a data format, much like your example.

Yet, wouldn't this be overkill? @idleberg would a JavaScript API be consumable in your use case?

@paulmelnikow
Copy link
Member

For an ideal experience in #701 we'd need name and possibly documentation and validation rules for each field, and a recipes for assembling the final string, with or without optional parameters like a branch. It would be good if some of that same code were used to define the server's route.

It would be nice to have a way of dealing with mightyiam/shields-badge-data#23 that makes it easier to quickly pick through all the badges e.g. for a given github repo.

@mightyiam
Copy link

Incorporating what I gathered from here, I have opened a PR on shields-badge-data.

@paulmelnikow
Copy link
Member

I'll take a look!

This was referenced Nov 8, 2018
Closed
Merged
@paulmelnikow paulmelnikow mentioned this issue Nov 26, 2018
Merged
paulmelnikow added a commit that referenced this issue Dec 2, 2018
@paulmelnikow
Service definition export format (#2397)
2045489 
Three main goals:

1. In the front end:
      a. Show form fields and automatically assemble badge URLs (#701)
      c. Group together examples for the same service
      b. Show deprecated services
2. Make it easy to changing the schema of `examples`, thanks to 100% validation. One challenge with frameworks is that when there are typos things fail silently which is pretty unfriendly to developers. The validation should really help with that. (This caught one bug in AUR, though I fixed it in #2405 which landed first.)
3. Produce a service definition export for external tool builders. (#776)
4. Build toward harmony between the front-end data structure and the `examples` key in the service classes. I aliased `staticPreview` to `staticExample` which starts this process.

The old format:

- Lacked a consistent machine-readable representation of the fields.
- Flattened multiple examples for the same service were flattened.
- Excluded deprecated services.

The new format improves a few things, too:

- It cleans up the naming. Since this file evolved over time, the names were a bit muddled (i.e. what was an example vs a preview).
- It duplicated information (like `.svg`). (I can imagine dropping the `.svg` from our badge URLs someday, which would make the URLs easier to read and maintain.)
- For a human reading the YAML file, providing the static example as a deconstructed object is more readable.

Here are a couple snippets:

```yml
  - category: build
    name: AppVeyorCi
    isDeprecated: false
    route:
      format: '([^/]+/[^/]+)(?:/(.+))?'
      queryParams: []
    examples:
      - title: AppVeyor
        example: {path: /appveyor/ci/gruntjs/grunt, queryParams: {}}
        preview: {label: build, message: passing, color: brightgreen}
        keywords: []
      - title: AppVeyor branch
        example: {path: /appveyor/ci/gruntjs/grunt/master, queryParams: {}}
        preview: {label: build, message: passing, color: brightgreen}
        keywords: []
  - category: downloads
    name: AmoDownloads
    isDeprecated: false
    examples:
      - title: Mozilla Add-on
        example: {path: /amo/d/dustman, queryParams: {}}
        preview: {path: /amo/d/dustman, queryParams: {}}
        keywords: [amo, firefox]
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
core Server, BaseService, GitHub auth, Shared helpers
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Service definition export format badges/shields
3 participants
@mightyiam @paulmelnikow @idleberg