Update documentation (#1129)
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
GitHub
141
CONTRIBUTING.md
141
CONTRIBUTING.md
@@ -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`.
|
||||
[](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:
|
||||
|
||||
[](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.
|
||||
|
||||
Reference in New Issue
Block a user