starterkit-lessons icon indicating copy to clipboard operation
starterkit-lessons copied to clipboard

Add editor config

Open alexpearce opened this issue 7 years ago • 6 comments

With lots of contributors having strong opinions on their text configuration, we should include a style guide and/or editor config file that defines how we format the lessons. This is partly to circumvent the need for style debates, and also to reduce the number of re-formatting changes made in PRs, which clutter the diff.

alexpearce avatar Feb 08 '18 08:02 alexpearce

Style suggestions:

  • ~80 character line length with breaks after whole words (to make change tracking easy) and with a space at the end of the line.
  • bullet points should not end in punctuation (e.g., the Learning Objectives, not the list in Contributing).

goi42 avatar Feb 08 '18 14:02 goi42

I prefer line break after sentence (easier to track changes). Maybe editor config doesn't handle this properly?

apuignav avatar Feb 08 '18 14:02 apuignav

That sounds reasonable to me. (I do my line-breaks in Markdown manually anyway.) If we break after each sentence, maybe suggest no hanging white-space?

goi42 avatar Feb 08 '18 14:02 goi42

I typed this earlier but then forgot to comment:

I've not really thought about this but perhaps we could have CI:

  • Autoformat merge requests when they're merged (one sentence per line, normalise whitespace)
  • Add a branch (travis-mr-XYZ) when merge requests are made and then leave a comment linking to the diff so a normalised diff can be viewed

It might make leaving comments on diffs a little more awkward but it would avoid requiring people to configure editors.

chrisburr avatar Feb 08 '18 14:02 chrisburr

I like that idea as it's basically impossible to enforce style-guides. And it's no more awkward than looking through commits that contain style-updates.

goi42 avatar Feb 08 '18 14:02 goi42

I like the idea a lot!

apuignav avatar Feb 08 '18 14:02 apuignav