CONTRIBUTING.md 6.6 KB
Newer Older
1
# Contributing to Shields
2

3 4
Shields is a community project. We invite your participation through
financial contributions, issues, and pull requests!
5

6
## Ways you can help
7

8 9 10 11 12 13 14 15
### Financial contributions

We welcome financial contributions in full transparency on our
[open collective](https://opencollective.com/shields). Anyone can file an
expense. If the expense makes sense for the development of the community, it
will be "merged" into the ledger of our open collective by the core
contributors and the person who filed the expense will be reimbursed.

Paul Melnikow's avatar
Paul Melnikow committed
16
### Contributing code
17

Paul Melnikow's avatar
Paul Melnikow committed
18 19
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:
20

Paul Melnikow's avatar
Paul Melnikow committed
21
[![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)
22

Paul Melnikow's avatar
Paul Melnikow committed
23 24 25 26
### Contributing documentation

You can help by improving the project's usage and developer instructions.

27 28
Tutorials are in [/doc](https://github.com/badges/shields/tree/master/doc):

29 30 31 32
- When you read the documentation, you can fix mistakes and add your own thoughts.
- When your pull request follows the documentation but the practice changed,
  consider pointing this out and change the documentation for the next person.

33 34 35 36 37 38 39 40
API documentation is at [contributing.shields.io](https://contributing.shields.io/):

- This documentation is generated by annotating the code with
  [JSDoc](https://jsdoc.app/about-getting-started.html) comments.
  [Example](https://github.com/badges/shields/blob/b3be4d94d5ef570b8daccfd088c343a958988843/core/base-service/base-json.js#L26-L41)
- Adding a JSDoc comment to some existing code is a great first contribution
  and a good way to familiarize yourself with the codebase

Paul Melnikow's avatar
Paul Melnikow committed
41 42
### Helping others

43 44 45
You can help with code review, which reduces bugs, and over time has a
wonderful side effect of making the code more readable and therefore more
approachable. It's also a great way to teach and learn. Feel free to jump in!
46 47
Be welcoming, appreciative, and helpful. You can perform first reviews of
simple changes, like badge additions. These are usually tagged with
48
[service badge][service badge pr tag].
49 50

Please review [these impeccable guidelines][code review guidelines].
51

52 53 54
You can monitor [issues][], [discussions][] and the [chat room][], and help
other people who have questions about contributing to Shields, or using it
for their projects.
Paul Melnikow's avatar
Paul Melnikow committed
55

56 57
Feel free to reach out to one of the [maintainers][]
if you need help getting started.
58

59
[service badge pr tag]: https://github.com/badges/shields/pulls?q=is%3Apr+is%3Aopen+label%3Aservice-badge
60
[code review guidelines]: https://kickstarter.engineering/a-guide-to-mindful-communication-in-code-reviews-48aab5282e5e
Paul Melnikow's avatar
Paul Melnikow committed
61
[issues]: https://github.com/badges/shields/issues
62
[discussions]: https://github.com/badges/shields/discussions
Paul Melnikow's avatar
Paul Melnikow committed
63
[chat room]: https://discordapp.com/invite/HjJCwm5
64
[maintainers]: https://github.com/badges/shields#project-leaders
Paul Melnikow's avatar
Paul Melnikow committed
65 66 67 68 69 70 71 72 73 74

### 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.

75 76
If you have a suggestion of your own, [search the open issues][issues]. If you
don't see it, feel free to [open a new issue][open an issue].
Paul Melnikow's avatar
Paul Melnikow committed
77

78
[open an issue]: https://github.com/badges/shields/issues/new/choose
79

Pyves's avatar
Pyves committed
80 81 82 83
### Spreading the word

Feel free to star the repository. This will help increase the visibility of the project, therefore attracting more users and contributors to Shields!

84
We're also asking for [one-time \$10 donations](https://opencollective.com/shields) from developers who use and love Shields, please spread the word!
85

86
## Getting help
87

Paul Melnikow's avatar
Paul Melnikow committed
88
There are three places to get help:
89

Paul Melnikow's avatar
Paul Melnikow committed
90
1. If you're new to the project, a good place to start is the [tutorial][].
91
2. If you need help getting started or implementing a change, [start a discussion][discussions]
92
   with your question. We promise it's okay to do that. If there is already an
93
   issue open for the feature you're working on, you can post there directly.
Paul Melnikow's avatar
Paul Melnikow committed
94
3. You can also join the [chat room][] and ask your question there.
95

Paul Melnikow's avatar
Paul Melnikow committed
96
[tutorial]: doc/TUTORIAL.md
97

98
## Badge guidelines
99

100
- Shields.io hosts integrations for services which are primarily
101
  used by developers or which are widely used by developers.
102
- The left-hand side of a badge should not advertise. It should be a lowercase _noun_
103
  succinctly describing the meaning of the right-hand side.
104 105
- Except for badges using the `social` style, logos should be _turned off by
  default_.
106 107 108 109
- Badges should not obtain data from undocumented or reverse-engineered API endpoints.
- Badges should not obtain data by scraping web pages - these are likely to break frequently.
  Whereas API publishers are incentivised to maintain a stable platform for their users,
  authors of web pages have no such incentive.
110 111 112
- Badges may require users to specify a token in the badge URL as long it is scoped only to
  fetching information and doesn't expose any sensitive information. Generating a token with the
  correct scope must be clearly documented.
113

114
## Badge URLs
115

116 117
- The format of new badges should be of the form `/SERVICE/NOUN/PARAMETERS`.
- There is further documentation on this in [badge-urls](https://github.com/badges/shields/blob/master/doc/badge-urls.md)
118

119
## Coding guidelines
120

121 122 123
### Prettier

This project formats its source code using Prettier. The most enjoyable way to
124
use Prettier is to let it format code for you when you save. You can [integrate
125 126
it into your editor][integrate prettier].

127 128
Whether you integrate it into your editor or not, a pre-commit hook will run
Prettier before a commit by default.
129 130 131

[integrate prettier]: https://prettier.io/docs/en/editors.html

Paul Melnikow's avatar
Paul Melnikow committed
132
### Tests
133

134
When adding or changing a service [please write tests][service-tests].
135

Paul Melnikow's avatar
Paul Melnikow committed
136 137
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.
138

Paul Melnikow's avatar
Paul Melnikow committed
139
e.g. **[Travis] Fix timeout issues**
140

Paul Melnikow's avatar
Paul Melnikow committed
141
When changing other code, please add unit tests.
142

143 144 145 146
To run the integration tests, you must have redis installed and in your PATH.
Use `brew install redis`, `yum install redis`, etc. The test runner will
start the server automatically.

147
[service-tests]: https://github.com/badges/shields/blob/master/doc/service-tests.md
148

Paul Melnikow's avatar
Paul Melnikow committed
149 150
### Code organization

chris48s's avatar
chris48s committed
151
There is a [High-level code walkthrough](doc/code-walkthrough.md) describing the layout of the project.
Paul Melnikow's avatar
Paul Melnikow committed
152

chris48s's avatar
chris48s committed
153
### Logos
Paul Melnikow's avatar
Paul Melnikow committed
154

chris48s's avatar
chris48s committed
155
We have [documentation for logo usage](doc/logos.md) which includes [contribution guidance](doc/logos.md#contributing-logos)