starterkit-lessons
starterkit-lessons copied to clipboard
Add editor config
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.
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).
I prefer line break after sentence (easier to track changes). Maybe editor config doesn't handle this properly?
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?
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.
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.
I like the idea a lot!