m-lab / traceroute-caller

A sidecar service which runs traceroute after a connection closes
Apache License 2.0
18 stars 5 forks source link

Update "Local Development" instructions in README.md #84

Closed SaiedKazemi closed 3 years ago

SaiedKazemi commented 3 years ago

This change is Reviewable

coveralls commented 3 years ago

Pull Request Test Coverage Report for Build 69


Totals Coverage Status
Change from base Build 65: 0.0%
Covered Lines: 1069
Relevant Lines: 1095

💛 - Coveralls
SaiedKazemi commented 3 years ago

Sorry, I didn't mean to impose my choice by adding $ to the commands. I just noticed that docker-compose version had $ and added it to the rest for consistency (please feel free to remove them).

SaiedKazemi commented 3 years ago

README.md, line 26 at r1 (raw file):

Previously, stephen-soltesz (Stephen Soltesz) wrote…
One of the things that we should document as part of our "conventions docs" to be helpful is "typical development environment." I use VSCode for most of my work, with a number of extensions, including "markdownlint". I've come to rely on this linter to tell me what's helpful or not in markdown docs. I've found that it does a good job of keeping the text readable whether it's generated output (e.g. html) or in it's raw text format. In this case, `markdownlint` cares about two cases where the `$` is present for `sh` text blocks. * When the command uses `$` it should show output. For example: `MD014/commands-show-output: Dollar signs used before commands without showing output` * When the command does not use `$` it is much easier for users following along to copy/paste the command. Because this README is structured as a HOWTO, I suggest leaving the commands without `$`. (I personally prefer HOWTOs that make it easy to copy the commands I'm supposed to run) If you prefer to keep the `$`, then I think we should use the guidance from markdownlint and include some output in the example.

Thanks for the context. It's now clear why some commands have $ and some don't. I like this style and suggest that we all adopt it (although we use different development environments).