ComputerSurge/shields
3
0
Fork 0
Code Pull Requests 1 Activity

Update documentation (#1129)

Browse Source 
I wrote a new readme and contributing guidelines, and took a rough pass through the rest of the documentation.
This commit is contained in:
Paul Melnikow
2017-10-14 11:43:52 -04:00
committed by GitHub
parent b0f2eed0cb
commit 16045fdff8
9 changed files with 480 additions and 327 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
CONTRIBUTING.md
View File

@@ -1,21 +1,96 @@
# Contribution Guidelines
Contributing to Shields
=======================
This is the home of Shields.io, home to the badge design specification, API documentation, and server code for Badges as a Service.
Shields is a community project! We invite your participation through issues
and pull requests.
We invite participation through [GitHub Issues][], which we use much like a discussion forum. This repository should only contain non-implementation specific topics: specifications, design, and the web site.
## This implementation
Ways you can help
-----------------
Please see [INSTALL.md][] for information on how to start contributing code to
shields.io.
You can read a [Tutorial on how to add a badge](doc/TUTORIAL.md).
### Contributing code
[INSTALL.md]: ./INSTALL.md
This project has quite a backlog of suggestions! If you're new to the project,
maybe you'd like to open a pull request to address one of them:
Note that the root gets redirected to <http://shields.io>.
For testing purposes, you can go to `http://localhost/try.html`.
[![GitHub issues by-label](https://img.shields.io/github/issues/badges/shields/good%20first%20issue.svg)](https://github.com/badges/shields/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
## Ground rules
Or you can adopt one of these pull requests:
[![GitHub issues by-label](https://img.shields.io/github/issues-pr/badges/shields/good%20first%20issue.svg)](https://github.com/badges/shields/pulls?q=is%3Apr+is%3Aopen+label%3A%22good+first+issue%22)
### Contributing documentation
You can help by improving the project's usage and developer instructions.
### Helping others
You can monitor [issues][] and the [chat room][] and help other people who
have questions about how to use Shields, or work on it.
[issues]: https://github.com/badges/shields/issues
[chat room]: https://discordapp.com/invite/HjJCwm5
### Suggesting improvements
There are _a lot_ of suggestions on file. You can help by weighing in on these
suggestions, which helps convey community need to other contributors who might
pick them up.
There is no need to post a new comment. Just add a :thumbsup: or :heart: to
the top post.
If you have a suggestion of your own, [search the open issues][issues] and if
you don't see it, feel free to [open a new issue][open an issue].
[open an issue]: https://github.com/badges/shields/issues/new
Getting help
------------
There are three places to get help:
1. If you're new to the project, a good place to start is the [tutorial][].
2. If you need help getting started or implementing a change, feel free to
[open an issue][] with your question.
3. You can also join the [chat room][] and ask your question there.
[tutorial]: doc/TUTORIAL.md
Coding guidelines
-----------------
### Tests
When adding or changing a service please write [tests][service-tests].
When opening a pull request, include your service name in brackets in the pull
request title. That way, those service tests will run in CI.
e.g. **[Travis] Fix timeout issues**
When changing other code, please add unit tests.
[service-tests]: https://github.com/badges/shields/blob/master/service-tests/README.md
### Code organization
Function declarations are placed in `lib/`, not directly in `server.js`.
Logos
-----
Please minimize checked-in `.svg` files through [SVGO][]. You can use [svgomg][].
[SVGO]: https://github.com/svg/svgo
[svgomg]: https://jakearchibald.github.io/svgomg/
Badge guidelines
----------------
- The left-hand side of a badge should not advertize. It should be a noun
describing succinctly the meaning of the right-hand-side data.
@@ -26,45 +101,5 @@ For testing purposes, you can go to `http://localhost/try.html`.
`/VENDOR/SUBVENDOR-BADGE-SPECIFIC/PARAMETERS.format`. For instance,
`https://img.shields.io/gitter/room/nwjs/nw.js.svg`. The vendor is gitter, the
badge is for rooms, the parameter is nwjs/nw.js, and the format is svg.
Please minimize `.svg` files (eg. in logo/) through [SVGO][] (eg. by using
[svgomg][]).
[SVGO]: https://github.com/svg/svgo
[svgomg]: https://jakearchibald.github.io/svgomg/
## Implementations
The main implementation, available at <http://shields.io>, has its code located in this repository.
Other systems that produce badges following the same design, hosted elsewhere, are listed below.
| website / AP | language | issues |
| --------------------------------- | ---------- | ---------------------------- |
| shielded | JavaScript | [shielded][shielded issues] |
| [buckler.repl.ca][] | Go | [buckler][buckler issues] |
| old img.shields.io (discontinued) | Python | [img.shields.io-old][] |
| DotBadge | C# | [DotBadge](https://github.com/rebornix/DotBadge/issues) |
Please report **bugs** and discuss implementation specific concerns (performance characteristics, etc.) in the repository for the respective implementation.
## Adding support for a service
Please [open an issue][new issue] if you'd like to use Shields badges for a project that isn't yet supported.
[shields.io]: http://shields.io/
[website]: https://github.com/badges/shields/tree/gh-pages
[GitHub Issues]: https://github.com/badges/shields/issues
[new issue]: https://github.com/badges/shields/issues/new
[img.shields.io]: http://img.shields.io/
[gh-badges issues]: https://github.com/badges/shields/issues
[primary]: https://github.com/badges/shields/issues/94
[shielded issues]: https://github.com/badges/shielded/issues
[buckler.repl.ca]: http://buckler.repl.ca/
[buckler issues]: https://github.com/badges/buckler/issues
[img.shields.io-old]: https://github.com/badges/img.shields.io-old/issues
- Except for badges using the `social` style, logos should be turned off by
default.

211
INSTALL.md
View File

@@ -1,211 +0,0 @@
# GitHub badges in SVG format
[![npm version](http://img.shields.io/npm/v/gh-badges.svg)](https://npmjs.org/package/gh-badges)
![coverage](https://rawgithub.com/badges/shields/master/coverage.svg)
[![build status](http://img.shields.io/travis/badges/gh-badges.svg)](https://travis-ci.org/badges/gh-badges)
Make your own badges [here][badges]! (Quick guide: `https://img.shields.io/badge/left-right-f39f37.svg`.)
[badges]: <http://shields.io/#your-badge>
# Install the API
```bash
npm install gh-badges
```
```js
var badge = require('gh-badges');
// Optional step, to have accurate text width computation.
badge.loadFont('/path/to/Verdana.ttf', function(err) {
badge({ text: ["build", "passed"], colorscheme: "green", template: "flat" },
function(svg, err) {
// svg is a String of your badge.
});
});
```
# Use the CLI
```bash
npm install -g gh-badges
badge build passed :green .png > mybadge.png
# Stored a PNG version of your badge on disk.
```
# Start the Server
To run the server you will need the following executables on your Path:
- [PhantomJS](http://www.phantomjs.org/)
On an OS X machine, [Homebrew](brew.sh) is a good package manager that will
allow you to install that.
On Ubuntu / Debian: `sudo apt-get install phantomjs`.
You will also need version 6 of Node.js.
The [Node.js documentation](https://nodejs.org/en/download/package-manager/) explains
how to install it on various systems.
On Ubuntu / Debian: `curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -; sudo apt-get install -y nodejs`.
```bash
git clone https://github.com/badges/shields.git
cd shields
npm install # You may need sudo for this.
sudo node server
```
The server uses port 80 by default, which requires `sudo` permissions.
There are two ways to provide an alternate port:
```bash
PORT=8080 node server
node server 8080
```
The root gets redirected to <http://shields.io>.
For testing purposes, you can go to `http://localhost/try.html`.
# Format
The format is the following:
```js
{
/* Textual information shown, in order. */
"text": [ "build", "passed" ],
"format": "svg", // Also supports "json".
"colorscheme": "green",
/* … Or… */
"colorA": "#555",
"colorB": "#4c1",
/* See templates/ for a list of available templates.
Each offers a different visual design. */
"template": "flat"
}
```
See also
- [colorscheme.json](lib/colorscheme.json) for the `colorscheme` option
- [templates/](templates) for the `template` option
# Defaults
If you want to add a colorscheme, head to `lib/colorscheme.json`. Each scheme
has a name and a [CSS/SVG color][] for the color used in the first box (for the
first piece of text, field `colorA`) and for the one used in the second box
(field `colorB`).
[CSS/SVG color]: http://www.w3.org/TR/SVG/types.html#DataTypeColor
```js
"green": {
"colorB": "#4c1"
}
```
Both `colorA` and `colorB` have default values. Usually, the first box uses the
same dark grey, so you can rely on that default value by not providing a
`"colorA"` field (such as above).
You can also use the `"colorA"` and `"colorB"` fields directly in the badges if
you don't want to make a color scheme for it. In that case, remove the
`"colorscheme"` field altogether.
# Making your Heroku badge server
Once you have installed the [Heroku Toolbelt][]:
[Heroku Toolbelt]: https://toolbelt.heroku.com/
```bash
heroku login
heroku create your-app-name
heroku config:set BUILDPACK_URL=https://github.com/mojodna/heroku-buildpack-multi.git#build-env
cp /path/to/Verdana.ttf .
make deploy
heroku open
```
# Docker
You can build and run the server locally using Docker. First build an image:
```console
$ docker build -t shields .
Sending build context to Docker daemon 3.923 MB
…
Successfully built 4471b442c220
```
Optionally, create a file called `shields.env` that contains the needed configuration. See
`shields.example.env` for an example.
Then run the container:
```console
$ docker run --rm -p 8080:80 --env-file shields.env --name shields shields
> gh-badges@1.1.2 start /usr/src/app
> node server.js
http://[::1]:80/try.html
```
Assuming Docker is running locally, you should be able to get to the application at http://localhost:8080/try.html. If you run Docker in a virtual machine (such as boot2docker or Docker Machine) then you will need to replace `localhost` with the actual IP address of that virtual machine.
# Build the index
Build the "real" index page:
```bash
make website
```
# Secret.json
Some services require the use of secret tokens or passwords. Those are stored in `private/secret.json` which is not checked into the repository, to avoid impersonation. Here is how it currently looks like:
```
bintray_apikey
bintray_user
gh_client_id
gh_client_secret
gh_token
gitter_dev_secret
shieldsIps
shieldsSecret
sl_insight_apiToken
sl_insight_userUuid
```
(Gathered from `cat private/secret.json | jq keys | grep -o '".*"' | sed 's/"//g'`.)
The `secret.tpl.json` is a template file used by the Docker container to set the secrets based on
environment variables.
# Main Server Sysadmin
- Servers in DNS round-robin:
- s0: 192.99.59.72 (vps71670.vps.ovh.ca)
- s1: 51.254.114.150 (vps244529.ovh.net)
- s2: 149.56.96.133 (vps117870.vps.ovh.ca)
- Self-signed TLS certificates, but `img.shields.io` is behind CloudFlare, which provides signed certificates.
- Using systemd to automatically restart the server when it crashes.
See https://github.com/badges/ServerScript for helper admin scripts.
# Links
See <https://github.com/h5bp/lazyweb-requests/issues/150> for a story of the
project's inception.
This is also available as a gem `badgerbadgerbadger`, [code here][gem].
[gem]: https://github.com/badges/badgerbadgerbadger
# License
All work here is licensed [CC0](LICENSE.md).

208
README.md
View File

@@ -1,5 +1,5 @@
<p align="center">
<img src="https://rawgit.com/badges/shields/master/logo.svg"
<img src="https://raw.githubusercontent.com/badges/shields/master/logo.svg"
height="130">
</p>
<p align="center">
@@ -15,55 +15,34 @@
<img src="https://img.shields.io/travis/badges/shields.svg"
alt="build status">
</a>
<a href="https://github.com/badges/shields/commits/gh-pages">
<img src="https://img.shields.io/github/last-commit/badges/shields/gh-pages.svg?label=last%20deployed"
alt="last deployed">
</a>
<a href="https://discord.gg/HjJCwm5">
<img src="https://img.shields.io/discord/308323056592486420.svg"
alt="chat on Discord">
</a>
</p>
<p align="center"><sup><strong>An image server for legible and concise information. Our <a href="http://shields.io/">Homepage</a> | <a href="https://twitter.com/shields_io">Twitter</a></strong></sup></p>
* **[INSTALL](INSTALL.md)** – installation instructions.
* **[CONTRIBUTING](CONTRIBUTING.md)** – project contribution guidelines.
* **[SPECIFICATION](spec/SPECIFICATION.md)** – spec for the visual design of Shields badges.
* **[LICENSE](LICENSE.md)** – public domain dedication.
[![Twitter](https://img.shields.io/twitter/follow/shields_io.svg?style=social)]()
Make your own badges [here][badges]! (Quick guide: `https://img.shields.io/badge/left-right-f39f37.svg`.)
This is home to [Shields.io][shields.io], a service for concise, consistent,
and legible badges in SVG and raster format, which can easily be included in
GitHub readmes or any other web page. The service supports dozens of
continuous integration services, package registries, distributions, app
stores, social networks, code coverage services, and code analysis services.
Every month it serves over 470 million images.
[badges]: <http://shields.io/#your-badge>
In addition to hosting the shields.io home page and server code, this monorepo
hosts an [NPM library for generating badges][gh-badges], and the badge design
specification.
## Solving the problem
Many GitHub repositories sport badges for things like:
<table>
<tr>
<td><a href="https://travis-ci.org/"><strong>Travis CI</strong></a><p><sup>(build status)</sup></p></td>
<td><img src="http://f.cl.ly/items/2H233M0I0T43313c3h0C/Screen%20Shot%202013-01-30%20at%202.45.30%20AM.png" alt="Travis CI badge"></td>
</tr>
<tr>
<td><a href="https://gemnasium.com/"><strong>Gemnasium</strong></a><p><sup>(dependency checks)</sup></p></td>
<td><img src="http://f.cl.ly/items/2j1D2R0q2C3s1x2y3k09/Screen%20Shot%202013-01-30%20at%202.46.10%20AM.png" alt="Gemnasium badge"></td>
</tr>
<tr>
<td><a href="http://codeclimate.com"><strong>Code Climate</strong></a><p><sup>(static analysis)</sup></p></td>
<td><img src="http://f.cl.ly/items/0H2O1A3q2b3j1D2i0M3j/Screen%20Shot%202013-01-30%20at%202.46.47%20AM.png" alt="Code Climate badge"></td>
</tr>
<tr>
<td><a href="http://rubygems.org"><strong>RubyGems</strong></a><p><sup>(released gem version)</sup></p></td>
<td><img src="http://f.cl.ly/items/443X21151h1V301s2s3a/Screen%20Shot%202013-01-30%20at%202.47.10%20AM.png" alt="RubyGems badge"></td>
</tr>
</table>
As you can see from the zoomed 400% versions of these badges above, nobody is (really) using the same badge file and at normal size, they're hardly legible. Worst of all, they're completely inconsistent. The information provided isn't of the same kind on each badge. The context is blurry, which doesn't make for a straightforward understanding of how these badges are relevant to the project they're attached to and what information they provide.
Examples
--------
## The Shields solution
As you can see below, without increasing the footprint of these badges, I've tried to increase legibility and coherence, removing useless text to decrease the horizontal length in the (likely) scenario that more of these badge thingies crop up on READMEs all across the land.
![Badge design](spec/proportions.png)
This badge design corresponds to an old and now deprecated version which has since been replaced by beautiful and scalable SVG versions that can be found on [shields.io](http://shields.io).
## Examples
What kind of metadata can you convey using badges?
* test build status: `build | failing`
* build status: `build | failing`
* code coverage percentage: `coverage | 80%`
* stable release version: `version | 1.2.3`
* package manager release: `gem | 1.2.3`
@@ -72,31 +51,136 @@ What kind of metadata can you convey using badges?
* [SemVer](http://semver.org/) version observance: `semver | 2.0.0`
* amount of [Gratipay](http://gratipay.com) donations per week: `tips | $2/week`
## Services using the Shields standard
* [Badger](https://github.com/badges/badgerbadgerbadger)
* [badges2svg](https://github.com/bfontaine/badges2svg)
* [CII Best Practices](https://bestpractices.coreinfrastructure.org/)
* [Codacy](https://www.codacy.com)
* [Code Climate](https://codeclimate.com/changelog/510d4fde56b102523a0004bf)
* [Coveralls](https://coveralls.io/)
* [docs.rs](https://docs.rs/)
* [Forkability](http://basicallydan.github.io/forkability/)
* [Gemnasium](http://support.gemnasium.com/forums/236528-general/suggestions/5518400-use-svg-for-badges-so-they-still-look-sharp-on-r)
* [GoDoc](https://godoc.org/)
* [PHPPackages](https://phppackages.org)
* [Read the Docs](https://readthedocs.org/)
* [reposs](https://github.com/rexfinn/reposs)
* [ruby-gem-downloads-badge](https://github.com/bogdanRada/ruby-gem-downloads-badge/)
* [Scrutinizer](https://scrutinizer-ci.com/)
* [Semaphore](https://semaphoreci.com)
* [Travis CI](https://github.com/travis-ci/travis-ci/issues/630#issuecomment-38054967)
* [Version Badge](http://badge.fury.io/)
* [VersionEye](https://www.versioneye.com/)
[Make your own badges][custom badges]!
(Quick guide: `https://img.shields.io/badge/left-right-f39f37.svg`.)
# Legal
Browse a [complete list of badges][shields.io].
[custom badges]: http://shields.io/#your-badge
Contributing
------------
Shields is a community project! We invite your participation through issues
and pull requests.
When adding or changing a service please add [tests][service-tests].
This project has quite a backlog of suggestions! If you're new to the project,
maybe you'd like to opan a pull request to address one of them:
[![GitHub issues by-label](https://img.shields.io/github/issues/badges/shields/good%20first%20issue.svg)](https://github.com/badges/shields/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
Or you can adopt one of these pull requests:
[![GitHub issues by-label](https://img.shields.io/github/issues-pr/badges/shields/good%20first%20issue.svg)](https://github.com/badges/shields/pulls?q=is%3Apr+is%3Aopen+label%3A%22good+first+issue%22)
You can read a [tutorial on how to add a badge][tutorial].
You can peruse the [contributing guidelines][contributing].
[service-tests]: https://github.com/badges/shields/blob/master/service-tests/README.md
[tutorial]: doc/TUTORIAL.md
[contributing]: CONTRIBUTING.md
Using the badge library
-----------------------
[![npm version](http://img.shields.io/npm/v/gh-badges.svg)](https://npmjs.org/package/gh-badges)
```sh
npm install -g gh-badges
badge build passed :green .png > mybadge.png
```
```js
const badge = require('gh-badges')
// Optional step, to have accurate text width computation.
const format = {
text: ['build', 'passed'],
colorscheme: 'green',
template: 'flat',
}
badge.loadFont('/path/to/Verdana.ttf', err => {
badge(format, (svg, err) => {
// svg is a string containing your badge
})})
```
View the [documentation for gh-badges][gh-badges doc].
**Note:** The badge library was last released in 2016.
[gh-badges doc]: doc/gh-badges.md
Development
-----------
1. Install Node 6 or later. You can use the [package manager][] of your choice.
2. Clone this repository.
3. Run `npm install` to install the dependencies.
4. Run `node server 1111 localhost` to start the server.
5. Open `http://localhost:1111/try.html` to view the home page.
[package manager]: https://nodejs.org/en/download/package-manager/
Hosting your own server
-----------------------
There is documentation about [hosting your own server][self-hosting].
[self-hosting]: doc/self-hosting.md
History
-------
The badge specification was developed in 2013 by [espadrine][] as part of a
library called [gh-badges][old-gh-badges], which then merged with shields.io,
badgr.co, and b.adge.me to form this project. You can read more about
[the project's inception][thread],
[the motivation of the SVG badge specification][motivation], and
[the specification itself][spec].
[espadrine]: https://github.com/espadrine
[old-gh-badges]: https://github.com/badges/gh-badges
[motivation]: spec/motivation.md
[spec]: spec/SPECIFICATION.md
[thread]: https://github.com/h5bp/lazyweb-requests/issues/150
Project leaders
---------------
[espadrine](https://github.com/espadrine) is the sysadmin.
These contributors donate time on a consistent basis to help guide and
maintain the project:
* [Daniel15](https://github.com/Daniel15)
* [espadrine](https://github.com/espadrine)
* [paulmelnikow](https://github.com/paulmelnikow)
Related projects
----------------
- [badgerbadgerbadger gem][gem]
[gem]: https://github.com/badges/badgerbadgerbadger
License
-------
All assets and code are under the [CC0 LICENSE](LICENSE.md) and in the public
domain unless specified otherwise.
The assets in `logo/` are trademarks of their respective companies and are under
their terms and license.
The assets in `logo/` are trademarks of their respective companies and are
under their terms and license.

1
coverage.svg
View File

@@ -1 +0,0 @@
<svg xmlns="http://www.w3.org/2000/svg" width="110" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><mask id="a"><rect width="110" height="20" rx="3" fill="#fff"/></mask><g mask="url(#a)"><path fill="#555" d="M0 0h63v20H0z"/><path fill="#dfb317" d="M63 0h47v20H63z"/><path fill="url(#b)" d="M0 0h110v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11"><text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text><text x="31.5" y="14">coverage</text><text x="85.5" y="15" fill="#010101" fill-opacity=".3">76.8%</text><text x="85.5" y="14">76.8%</text></g></svg>
Side by Side

Before

Width:  |  Height:  |  Size: 744 B

51
doc/gh-badges.md Normal file
View File

@@ -0,0 +1,51 @@
Format
------
The format is the following:
```js
{
text: [ 'build', 'passed' ], // Textual information shown, in order
format: 'svg', // Also supports json
colorscheme: 'green',
// or ...
colorA: '#555',
colorB: '#4c1',
// See templates/ for a list of available templates.
// Each offers a different visual design.
template: 'flat',
}
```
### See also
- [colorscheme.json](lib/colorscheme.json) for the `colorscheme` option
- [templates/](templates) for the `template` option
Defaults
--------
If you want to add a colorscheme, head to `lib/colorscheme.json`. Each scheme
has a name and a [CSS/SVG color][] for the color used in the first box (for the
first piece of text, field `colorA`) and for the one used in the second box
(field `colorB`).
[CSS/SVG color]: http://www.w3.org/TR/SVG/types.html#DataTypeColor
```js
"green": {
"colorB": "#4c1"
}
```
Both `colorA` and `colorB` have default values. Usually, the first box uses the
same dark grey, so you can rely on that default value by not providing a
`"colorA"` field (such as above).
You can also use the `"colorA"` and `"colorB"` fields directly in the badges if
you don't want to make a color scheme for it. In that case, remove the
`"colorscheme"` field altogether.

38
doc/production-hosting.md Normal file
View File

@@ -0,0 +1,38 @@
Production hosting
==================
Server secrets
--------------
Some services require the use of secret tokens or passwords. Those are stored
in `private/secret.json` which is not checked into the repository.
These settings are currently set on the production server:
- bintray_apikey
- bintray_user
- gh_client_id
- gh_client_secret
- gh_token
- gitter_dev_secret
- shieldsIps
- shieldsSecret
- sl_insight_apiToken
- sl_insight_userUuid
(Gathered from `cat private/secret.json | jq keys | grep -o '".*"' | sed 's/"//g'`.)
The `secret.tpl.json` is a template file used by the Docker container to set the secrets based on
environment variables.
Main Server Sysadmin
--------------------
- Servers in DNS round-robin:
- s0: 192.99.59.72 (vps71670.vps.ovh.ca)
- s1: 51.254.114.150 (vps244529.ovh.net)
- s2: 149.56.96.133 (vps117870.vps.ovh.ca)
- Self-signed TLS certificates, but `img.shields.io` is behind CloudFlare, which provides signed certificates.
- Using systemd to automatically restart the server when it crashes.
See https://github.com/badges/ServerScript for helper admin scripts.

106
doc/self-hosting.md Normal file
View File

@@ -0,0 +1,106 @@
Hosting your own Shields server
===============================
Installation
------------
You will need version 6 of Node.js, which you can install using a
[package manager][].
On Ubuntu / Debian:
```sh
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -; sudo apt-get install -y nodejs
```
```sh
git clone https://github.com/badges/shields.git
cd shields
npm install # You may need sudo for this.
```
[package manager]: https://nodejs.org/en/download/package-manager/
Build the index
---------------
Build the "real" index page:
```sh
make website
```
Start the server
----------------
```sh
sudo node server
```
The server uses port 80 by default, which requires `sudo` permissions.
There are two ways to provide an alternate port:
```sh
PORT=8080 node server
node server 8080
```
The root gets redirected to https://shields.io.
For testing purposes, you can go to `http://localhost/try.html`.
Heroku
------
Once you have installed the [Heroku Toolbelt][]:
```bash
heroku login
heroku create your-app-name
heroku config:set BUILDPACK_URL=https://github.com/mojodna/heroku-buildpack-multi.git#build-env
cp /path/to/Verdana.ttf .
make deploy
heroku open
```
[Heroku Toolbelt]: https://toolbelt.heroku.com/
Docker
------
You can build and run the server locally using Docker. First build an image:
```console
$ docker build -t shields .
Sending build context to Docker daemon 3.923 MB
…
Successfully built 4471b442c220
```
Optionally, create a file called `shields.env` that contains the needed
configuration. See [shields.example.env][shields.example.env] for an example.
Then run the container:
```console
$ docker run --rm -p 8080:80 --env-file shields.env --name shields shields
> gh-badges@1.1.2 start /usr/src/app
> node server.js
http://[::1]:80/try.html
```
Assuming Docker is running locally, you should be able to get to the
application at http://localhost:8080/try.html.
If you run Docker in a virtual machine (such as boot2docker or Docker Machine)
then you will need to replace `localhost` with the IP address of that virtual
machine.
[shields.example.env]: ../shields.example.env

29
spec/motivation.md Normal file
View File

@@ -0,0 +1,29 @@
## Solving the problem
Many GitHub repositories sport badges for things like:
<table>
<tr>
<td><a href="https://travis-ci.org/"><strong>Travis CI</strong></a><p><sup>(build status)</sup></p></td>
<td><img src="http://f.cl.ly/items/2H233M0I0T43313c3h0C/Screen%20Shot%202013-01-30%20at%202.45.30%20AM.png" alt="Travis CI badge"></td>
</tr>
<tr>
<td><a href="https://gemnasium.com/"><strong>Gemnasium</strong></a><p><sup>(dependency checks)</sup></p></td>
<td><img src="http://f.cl.ly/items/2j1D2R0q2C3s1x2y3k09/Screen%20Shot%202013-01-30%20at%202.46.10%20AM.png" alt="Gemnasium badge"></td>
</tr>
<tr>
<td><a href="http://codeclimate.com"><strong>Code Climate</strong></a><p><sup>(static analysis)</sup></p></td>
<td><img src="http://f.cl.ly/items/0H2O1A3q2b3j1D2i0M3j/Screen%20Shot%202013-01-30%20at%202.46.47%20AM.png" alt="Code Climate badge"></td>
</tr>
<tr>
<td><a href="http://rubygems.org"><strong>RubyGems</strong></a><p><sup>(released gem version)</sup></p></td>
<td><img src="http://f.cl.ly/items/443X21151h1V301s2s3a/Screen%20Shot%202013-01-30%20at%202.47.10%20AM.png" alt="RubyGems badge"></td>
</tr>
</table>
As you can see from the zoomed 400% versions of these badges above, nobody is (really) using the same badge file and at normal size, they're hardly legible. Worst of all, they're completely inconsistent. The information provided isn't of the same kind on each badge. The context is blurry, which doesn't make for a straightforward understanding of how these badges are relevant to the project they're attached to and what information they provide.
## The Shields solution
As you can see below, without increasing the footprint of these badges, I've tried to increase legibility and coherence, removing useless text to decrease the horizontal length in the (likely) scenario that more of these badge thingies crop up on READMEs all across the land.
![Badge design](spec/proportions.png)
This badge design corresponds to an old and now deprecated version which has since been replaced by beautiful and scalable SVG versions that can be found on [shields.io](http://shields.io)

22
spec/users.md Normal file
View File

@@ -0,0 +1,22 @@
Services using the Shields standard
===================================
* [Badger](https://github.com/badges/badgerbadgerbadger)
* [badges2svg](https://github.com/bfontaine/badges2svg)
* [CII Best Practices](https://bestpractices.coreinfrastructure.org/)
* [Codacy](https://www.codacy.com)
* [Code Climate](https://codeclimate.com/changelog/510d4fde56b102523a0004bf)
* [Coveralls](https://coveralls.io/)
* [docs.rs](https://docs.rs/)
* [Forkability](http://basicallydan.github.io/forkability/)
* [Gemnasium](http://support.gemnasium.com/forums/236528-general/suggestions/5518400-use-svg-for-badges-so-they-still-look-sharp-on-r)
* [GoDoc](https://godoc.org/)
* [PHPPackages](https://phppackages.org)
* [Read the Docs](https://readthedocs.org/)
* [reposs](https://github.com/rexfinn/reposs)
* [ruby-gem-downloads-badge](https://github.com/bogdanRada/ruby-gem-downloads-badge/)
* [Scrutinizer](https://scrutinizer-ci.com/)
* [Semaphore](https://semaphoreci.com)
* [Travis CI](https://github.com/travis-ci/travis-ci/issues/630#issuecomment-38054967)
* [Version Badge](http://badge.fury.io/)
* [VersionEye](https://www.versioneye.com/)