Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Test examples/ping-*/README.md #157

Merged
merged 11 commits into from
Jul 6, 2016
Merged

Test examples/ping-*/README.md #157

merged 11 commits into from
Jul 6, 2016

Conversation

motiejus
Copy link
Contributor

@motiejus motiejus commented Jul 1, 2016

Using cram to execute and verify instructions in the following files:

  • examples/ping-json/README.md
  • examples/ping-thrift-gen/README.md
  • examples/ping-thrift/README.md

Currently, all of the tests are failing due to incomplete instructions in the README, but opening the pull request anyway to set the path forward to fixing them.

motiejus added 5 commits July 1, 2016 13:41
Fails with the following output:

       $ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}'
    -  {"ok":true,"head":null,"body":{"message":"Hello, world!","from":"127.0.0.1:300?","p":""},"headers":{"as":"json"},"trace":"*"} (glob)
    +  {"ok":true,"head":null,"body":{"message":"Hello, world!","from":"127.0.0.1:3001","pheader":""},"headers":{"as":"json"},"trace":"dfabd0ded0c75adc"}
Fails with the following output:

       $ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}' --headers '{"p": "my_header"}'
    -  {"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:300?","pheader":"my_header"},"headers":{"as":"thrift"},"trace":"*"} (glob)
    +  TchannelBadRequestError: no handler for service "pingchannel" and method "/ping"
    +  {"ok":false,"name":"TchannelBadRequestError","message":"no handler for service \"pingchannel\" and method \"/ping\"","isError":true,"isErrorFrame":true,"errorCode":6,"type":"tchannel.bad-request","fullType":"tchannel.bad-request"}
Fails with the following output:

       $ tcurl pingchannel -P hosts.json /ping '{"key": "my_key"}' --headers '{"p": "my_header"}'
    -  {"ok":true,"head":{},"body":{"message":"Hello, world!","from_":"127.0.0.1:300?","pheader":"my_header"},"headers":{"as":"thrift"},"trace":"*"} (glob)
    +  TchannelBadRequestError: no handler for service "pingchannel" and method "/ping"
    +  {"ok":false,"name":"TchannelBadRequestError","message":"no handler for service \"pingchannel\" and method \"/ping\"","isError":true,"isErrorFrame":true,"errorCode":6,"type":"tchannel.bad-request","fullType":"tchannel.bad-request"}
@@ -3,6 +3,12 @@ go:
- 1.6
- 1.5

sudo: false
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is sudo: false required? IIRC, this is the default

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leftovers from development process. Good catch, removed.

@motiejus motiejus force-pushed the motiejus-glide-examples branch from 63f7f04 to 589a102 Compare July 1, 2016 12:06
@motiejus motiejus force-pushed the motiejus-glide-examples branch from 589a102 to 32aed65 Compare July 1, 2016 12:07
@coveralls
Copy link

coveralls commented Jul 1, 2016

Coverage Status

Coverage decreased (-0.05%) to 94.621% when pulling 44cbefc on motiejus-glide-examples into 6a77220 on dev.

@coveralls
Copy link

coveralls commented Jul 1, 2016

Coverage Status

Coverage increased (+0.1%) to 94.785% when pulling 32aed65 on motiejus-glide-examples into 6a77220 on dev.

@coveralls
Copy link

coveralls commented Jul 1, 2016

Coverage Status

Coverage increased (+0.09%) to 94.761% when pulling 32aed65 on motiejus-glide-examples into 6a77220 on dev.

@coveralls
Copy link

coveralls commented Jul 1, 2016

Coverage Status

Coverage increased (+0.1%) to 94.785% when pulling 32aed65 on motiejus-glide-examples into 6a77220 on dev.

@dansimau
Copy link
Contributor

dansimau commented Jul 6, 2016

LGTM, happy to merge, though I do have this philosophical thought:

Is storing the tests in the README actually a good idea? I know it seems cool because it's less files or whatever, but it is sane/obvious/intuitive?

Note we have sacrificed formatting in the README to do this:
https://github.com/uber/ringpop-go/blob/32aed6541ce6ae53100d81f82a47ce7fe346e90a/examples/ping-json/README.md#running-the-example

I don't feel strongly enough about this to block the merge of this PR. Practically, I don't think this will cause us a huge issue/effort in the future. But I do think tests in the README is a bit strange and may increase the average WTFs/min in the codebase.

@motiejus
Copy link
Contributor Author

motiejus commented Jul 6, 2016

@dansimau thanks for the comment, and this is indeed a good philosophical discussion.

If we look at what we want to achieve:

  • Have clear instructions on how to build and use the project.
  • Make sure the instructions are sane (= automatically tested).

I see two approaches:

  1. More common: separate the documentation generation and testing. Usually deliverable is a docbook- or a sphinx-like documentation artifact, which, in the back, nobody cares how it's generated.
  2. Less common: test the actual final documentation.
  3. Move the steps from README to a script, and test the script.

(1) is a standard practice. However, since github does not really allow it easily (I want the README to be readable as-is).
(2) gives more wtfs/minute, but it will work, as long as people keep adding the correct examples.
(3) seems to be least wtfs/minute, but leads to a least readable README.

@motiejus
Copy link
Contributor Author

motiejus commented Jul 6, 2016

cc @severb can you check out the examples?

set -euo pipefail


declare cram_opts="-v --shell=/bin/bash"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't like the formatting of the README.md files now. Due to only two spaces they are hard to read on github. if we add --indent=4 to the cram options we can indent the code blocks by 4 spaces which will put a box around them in markdown making it a bit easier to read IMHO.

4 spaces looks much better on github
@coveralls
Copy link

coveralls commented Jul 6, 2016

Coverage Status

Coverage remained the same at 94.668% when pulling 98552ea on motiejus-glide-examples into 6a77220 on dev.

@coveralls
Copy link

coveralls commented Jul 6, 2016

Coverage Status

Coverage increased (+0.1%) to 94.785% when pulling 6042e48 on motiejus-glide-examples into 6a77220 on dev.

@thanodnl
Copy link
Contributor

thanodnl commented Jul 6, 2016

LGTM

@motiejus
Copy link
Contributor Author

motiejus commented Jul 6, 2016

@dansimau we actually fixed the formatting in README. Can you re-check?

@dansimau
Copy link
Contributor

dansimau commented Jul 6, 2016

LGTM

@coveralls
Copy link

coveralls commented Jul 6, 2016

Coverage Status

Coverage remained the same at 94.668% when pulling 1c5ab95 on motiejus-glide-examples into 2abc28c on dev.

@motiejus motiejus merged commit 35a2589 into dev Jul 6, 2016
@motiejus motiejus deleted the motiejus-glide-examples branch July 6, 2016 16:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants