-
-
Notifications
You must be signed in to change notification settings - Fork 5.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
I wrote a new readme and contributing guidelines, and took a rough pass through the rest of the documentation.
- Loading branch information
1 parent
b0f2eed
commit 16045fd
Showing
9 changed files
with
481 additions
and
328 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,70 +1,105 @@ | ||
| # 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`. | ||
| [](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: | ||
|
|
||
| - 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. | ||
| - New query parameters (such as `?label=` or `?style=`) should apply to any | ||
| requested badge. They must be registered in the cache (see `LruCache` in | ||
| `server.js`). | ||
| - The format of new badges should be of the form | ||
| `/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. | ||
| [](https://github.com/badges/shields/pulls?q=is%3Apr+is%3Aopen+label%3A%22good+first+issue%22) | ||
|
|
||
| Please minimize `.svg` files (eg. in logo/) through [SVGO][] (eg. by using | ||
| [svgomg][]). | ||
| ### 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 | ||
|
|
||
| [SVGO]: https://github.com/svg/svgo | ||
| [svgomg]: https://jakearchibald.github.io/svgomg/ | ||
|
|
||
| ## Implementations | ||
| Getting help | ||
| ------------ | ||
|
|
||
| The main implementation, available at <http://shields.io>, has its code located in this repository. | ||
| There are three places to get help: | ||
|
|
||
| Other systems that produce badges following the same design, hosted elsewhere, are listed below. | ||
| 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. | ||
|
|
||
| | 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) | | ||
| [tutorial]: doc/TUTORIAL.md | ||
|
|
||
| Please report **bugs** and discuss implementation specific concerns (performance characteristics, etc.) in the repository for the respective implementation. | ||
|
|
||
| ## Adding support for a service | ||
| Coding guidelines | ||
| ----------------- | ||
|
|
||
| Please [open an issue][new issue] if you'd like to use Shields badges for a project that isn't yet supported. | ||
| ### Tests | ||
|
|
||
| When adding or changing a service please write [tests][service-tests]. | ||
|
|
||
| [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 | ||
| 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. | ||
|
|
||
| [img.shields.io]: http://img.shields.io/ | ||
| [gh-badges issues]: https://github.com/badges/shields/issues | ||
| [primary]: https://github.com/badges/shields/issues/94 | ||
| e.g. **[Travis] Fix timeout issues** | ||
|
|
||
| [shielded issues]: https://github.com/badges/shielded/issues | ||
| When changing other code, please add unit tests. | ||
|
|
||
| [buckler.repl.ca]: http://buckler.repl.ca/ | ||
| [buckler issues]: https://github.com/badges/buckler/issues | ||
| [service-tests]: https://github.com/badges/shields/blob/master/service-tests/README.md | ||
|
|
||
| [img.shields.io-old]: https://github.com/badges/img.shields.io-old/issues | ||
| ### 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. | ||
| - New query parameters (such as `?label=` or `?style=`) should apply to any | ||
| requested badge. They must be registered in the cache (see `LruCache` in | ||
| `server.js`). | ||
| - The format of new badges should be of the form | ||
| `/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. | ||
| - Except for badges using the `social` style, logos should be turned off by | ||
| default. |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.