README: Minor stylistic changes, add documentation links

[EricCousineau-TRI]

• Discourages (or rather does not encourage) use of sudo make [un]install - it's a Bad Idea™
• Updates Markdown formatting
• Add explicit links to sdf_tutorials and sdformat.org

[EricCousineau-TRI]

Preview: https://github.com/EricCousineau-TRI/sdformat/blob/feature-2020-04-15-readme/README.md

[EricCousineau-TRI]

What is the review policy for this repo? When do I squash? (I really like to make sure my commits are curated, esp. now that BitBucket is no longer being used.)

[chapulina]

What is the review policy for this repo? When do I squash?

We're still figuring these things out internally. Suggestions are very welcome.

[EricCousineau-TRI]

I like the ROS2 guidelines (when using plain vanilla GitHub review), which is to always have fast-forward pushes for review, but then curate commits at the end, possibly after approval.
https://index.ros.org/doc/ros2/Contributing/Developer-Guide/#pull-requests

Would that work for you?

[EricCousineau-TRI]

Ooh, also, @scpeters and @azeey and I may try out Reviewable (example draft PR here: gazebosim/sdf_tutorials#3). This is perhaps not actionable now, but I could let you know how that goes for us?

[chapulina]

always have fast-forward pushes for review, but then curate commits at the end, possibly after approval.

That sounds reasonable to me, we'll discuss this as a team next week.

Reviewable

We're also planning to discuss this. My main concern is the recommendation to not mix the GitHub and Reviewable interfaces. Do you have any experience mixing both?

The entire team at Open Robotics should be able to open and review SDFormat PRs. We should also strive to have a consistent workflow for the entire Ignition family. So it sounds like we either use Reviewable for all projects or none.

[EricCousineau-TRI]

That sounds reasonable to me, we'll discuss this as a team next week.

Sounds good. For this PR, I will wait for Approval, then curate my commits.

[...] Do you have any experience mixing both?

We just tried it out here: gazebosim/sdf_tutorials#3 (review)
Basically, it works from GitHub to Reviewable (i.e. I see a new discussion in Reviewable, started by the GitHub item). However, once I responded in Reviewable, it did not go back to the GitHub discussion, as we've noted here for Drake:
https://drake.mit.edu/reviewable.html#github-integration
I think that can easily be solved by just referencing it.

The main issue we've had is mixing the request of review between GitHub (assigning reviewers in the sidebar) vs Reviewable (+@username). It does not always recognize GitHub assignment, so we generally stick to Reviewable assignments. [*]

So overall, the mixing between GitHub and Reviewable is not the most convenient, but may be workable.
Additionally, once we've become accustomed to Reviewable, it's wayyy easier to know that everything has been addressed in the review (and really easy to get the most de-cluttered view of it), with minimal effort of going back and looking through conversation history or what not in GitHub. The excessive client-side stuff is a bit annoying, but eh, overall I say worth it.

Understandably, this may not work for y'all, but I would recommend people taking it out for a test run. It's easy to point Reviewable to a PR to try it out on.

---

[*] We also have the following completion script, so it's unclear if this is due to our custom completion script (meant to handle labels and such):
https://github.com/RobotLocomotion/drake-ci/wiki/reviewable.io-review-completion-condition

[EricCousineau-TRI]

Are there any action items remaining here?

[EricCousineau-TRI]

Squashed to two curated commits

[EricCousineau-TRI]

And thanks!