add tutorial on how to add a new service #889

niccokunzmann · 2017-03-16T22:27:24Z

This was developed during #886.
I will see where I can link to this. Suggestions welcome.

This was developed during ecd3048

paulmelnikow · 2017-03-28T19:58:44Z

HowToAddANewService.md

+
+This changes the index.html file automatically.
+
+## (5) Create a Pull Request


Since contributors could be coming from any language or system, it's reasonable to guide them through the steps of using Node. However, let's assume they already know git and github. I appreciate that you want to make this a beginner tutorial, however including this text means we need to maintain it, and I don't see a lot of benefit in that. It's also effectively noise for most contributors, which detracts from the rest of the text. Could you replace it with a helpful link?

paulmelnikow · 2017-03-28T19:59:51Z

HowToAddANewService.md

+  badgeData.colorB = '#008bb8';   // (4)
+  sendBadge(format, badgeData);   // (5)
+}));
+```


This code would be a bit more readable if you lined up the numbers to the right. If you add js after the first set of backticks, GitHub will highlight it correctly.

paulmelnikow · 2017-03-28T20:01:14Z

HowToAddANewService.md

+2. Quit the running server with `Control+C`.
+3. Start the server again.  
+   `node server.js 8080`
+4. Visit the badge at [http://[::1]:8080/test/asd/fgh.svg](http://[::1]:8080/test/asd/fgh.svg).


A screenshot would be helpful here, for clarifying what asd and fgh do. example1 might be a name than test.

Note for me: todo

done in a1da13e

paulmelnikow · 2017-03-28T20:02:04Z

HowToAddANewService.md

+----------------
+
+Make sure, you can get the data somehow, best as JSON.
+There might be an API for your service delivering the data.


Could you move this mention down to 4.1, where you discuss querying an API?

paulmelnikow · 2017-03-28T20:02:49Z

HowToAddANewService.md

+7. Run the server  
+   `node server.js 8080`
+8. Visit the website to check the badges get loaded slowly:  
+   [http://[::1]:8080/try.html](http://[::1]/try.html)


Super-helpful!

paulmelnikow · 2017-03-28T20:03:48Z

HowToAddANewService.md

+   `git clone git@github.com:YOURGITHUBUSERNAME/shields.git`
+3. `cd shields`
+4. Install npm  
+   `sudo apt-get install npm nodejs-legacy curl`


Install imagemagick?

I will check if it was pre-installed.

Note for me: todo

done. (it was installed on my Ubuntu)

paulmelnikow · 2017-03-28T20:04:24Z

HowToAddANewService.md

+    <td><img src='/test/first/second.svg' alt=''/></td>
+    <td><code>https://img.shields.io/test/first/second.svg</code></td>
+  </tr>
+```


Thanks for including this.

paulmelnikow · 2017-03-28T20:05:31Z

HowToAddANewService.md

+There are various examples on how to answer with a customized badge:
+
+- [docker automated builds](https://github.com/badges/shields/blob/bf373d11cd522835f198b50b4e1719027a0a2184/server.js#L5014)
+- [the famous travis badge](https://github.com/badges/shields/blob/bf373d11cd522835f198b50b4e1719027a0a2184/server.js#L431)


I don't think it would hurt to inline these examples.

I recognized that you created a new tag for such contributions. I would rather refer to that tag than the two example: https://github.com/badges/shields/pulls?utf8=%E2%9C%93&q=is%3Apr%20label%3Anew-badge%20

What do you mean by inline?

Note for me: todo

@paulmelnikow Thanks for taking the time for feedback. This is the only comment I did not address. Could you tell me what inline means or what you expect? Maybe an example?

Glad to give feedback, it's my pleasure. I should have explained better about inlining. I'm asking if you could take an example that uses an API, and paste the code block right into the tutorial, just like you did with the non-API example above. Pasting in the code makes it easier for the reader to study the patterns they should use.

paulmelnikow · 2017-03-28T20:10:01Z

HowToAddANewService.md

+You should read the following:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [INSTALL.md](INSTALL.md)


Most of INSTALL.md is irrelevant. Could you mention it below, for further reading?

paulmelnikow · 2017-03-28T20:11:40Z

HowToAddANewService.md

@@ -0,0 +1,157 @@
+Tutorial on how to add a badge for a service
+============================================


Could you move this to doc/TUTORIAL.md, and add a link to it in CONTRIBUTING.md?

paulmelnikow · 2017-03-28T20:17:46Z

Thanks for this contribution! I left a handful of mostly minor comments. Think we could do a bit of consolidation of the developer docs, and this feels like a good start. 👍

badges#889 (comment)

paulmelnikow · 2017-03-30T02:14:14Z

doc/TUTORIAL.md

+You can read
+
+- previous successful pull-requests to see how other people implemented their badges.
+  You can as [merged pull-requests][mergedpr].


Looks like this sentence is missing a couple words? ^^

paulmelnikow · 2017-03-30T02:15:50Z

Looking good! Thanks for all the edits.

badges#889 (comment)

niccokunzmann · 2017-03-30T07:06:21Z

@paulmelnikow I pushed a description of the docker build as an example for an API query.
If you or an other person likes, you can review again.
I believe, I addressed all your comments from above.

niccokunzmann · 2017-03-30T07:26:14Z

I read through all of it. From my perspective I see nothing to improve.
I want to create an issue to fill the section about Authentication once this is merged.

paulmelnikow · 2017-03-30T15:46:30Z

Thanks so much!

niccokunzmann and others added 3 commits March 16, 2017 15:25

add tutorial on how to add a new service

7dff151

This was developed during ecd3048

numbered headings

c8306ab

Corrected Links

01ce535

paulmelnikow added the docs label Mar 27, 2017

paulmelnikow mentioned this pull request Mar 27, 2017

add format documentation links #887

Merged

paulmelnikow requested changes Mar 28, 2017

View reviewed changes

niccokunzmann added 11 commits March 29, 2017 10:59

moved tutorial to doc folder and linked in contributing.md

ef10c78

badges#889 (comment)

moved install.md to further reading

085db06

adjusted relative links

a5bc14e

badges#889 (comment)

moved taxt to api section

8053c39

badges#889 (comment)

improved code readability

0e29fc3

badges#889 (comment)

added pull-request link for new badges

858b447

badges#889 (comment)

replaced description by link to how to

690ff43

badges#889 (comment)

add edit link for including first-timer-perspective

640f0be

install imagemagick

6bd729f

badges#889 (comment)

add example image

a1da13e

badges#889 (comment)

Link to Regex

2786f51

paulmelnikow requested changes Mar 30, 2017

View reviewed changes

niccokunzmann added 3 commits March 30, 2017 08:01

add links to find pull-requests for other implementations

85462b0

add explanation of api query

05ba98d

badges#889 (comment)

consistent use of subject/STATUS though tutorial

1192e53

niccokunzmann added 2 commits March 30, 2017 09:17

read-though, removing errors

1699a28

add knowledge about authentication

88c2405

paulmelnikow approved these changes Mar 30, 2017

View reviewed changes

paulmelnikow merged commit 21a3aef into badges:master Mar 30, 2017

niccokunzmann deleted the add-starter-tutorial branch March 31, 2017 08:00

niccokunzmann restored the add-starter-tutorial branch March 31, 2017 08:01

paulmelnikow added the developer-experience Dev tooling, test framework, and CI label Apr 17, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add tutorial on how to add a new service #889

add tutorial on how to add a new service #889

niccokunzmann commented Mar 16, 2017

paulmelnikow Mar 28, 2017

paulmelnikow Mar 28, 2017

paulmelnikow Mar 28, 2017

niccokunzmann Mar 29, 2017

niccokunzmann Mar 29, 2017

paulmelnikow Mar 28, 2017

paulmelnikow Mar 28, 2017

paulmelnikow Mar 28, 2017

niccokunzmann Mar 29, 2017

niccokunzmann Mar 29, 2017

niccokunzmann Mar 29, 2017

paulmelnikow Mar 28, 2017

paulmelnikow Mar 28, 2017

niccokunzmann Mar 29, 2017

niccokunzmann Mar 29, 2017

niccokunzmann Mar 29, 2017

niccokunzmann Mar 29, 2017

paulmelnikow Mar 29, 2017

paulmelnikow Mar 28, 2017

paulmelnikow Mar 28, 2017

paulmelnikow commented Mar 28, 2017

paulmelnikow Mar 30, 2017

paulmelnikow commented Mar 30, 2017

niccokunzmann commented Mar 30, 2017

niccokunzmann commented Mar 30, 2017 •

edited

paulmelnikow commented Mar 30, 2017


		This changes the index.html file automatically.

		## (5) Create a Pull Request

		@@ -0,0 +1,157 @@
		Tutorial on how to add a badge for a service
		============================================

add tutorial on how to add a new service #889

add tutorial on how to add a new service #889

Conversation

niccokunzmann commented Mar 16, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulmelnikow commented Mar 28, 2017

Choose a reason for hiding this comment

paulmelnikow commented Mar 30, 2017

niccokunzmann commented Mar 30, 2017

niccokunzmann commented Mar 30, 2017 • edited

paulmelnikow commented Mar 30, 2017

niccokunzmann commented Mar 30, 2017 •

edited