◊(Local Yarn Code "Style Guide")

These are notes for my own use.

Prose

• The Local Yarn should be italicized.
• The Local Yarn is emphatically not “a web site”.

Punctuation

• In a list of actions, list items should end with a period.
• In a list of things, list items should not end with a period.
• Place trailing commas and periods outside of quotation marks unless they are part of the quoted text.
• Em- and en-dashes, “smart” quotes and apostrophes, emoji, and math symbols should be stored as such in the original text source. Do not rely on smartypants-style text processing at any step after writing to produce typographically correct punctuation.

Source files

• Header comment includes copyright notice, license information, and author contact info.
• Lines should be hard-wrapped at ≈100 characters. This includes prose sources.
• (Racket) All comments on their own line begin with ;;

Pre-commit checklist

1. Run fossil changes --differ to ensure no extra files need to be added.
2. Run fossil diff --tk to ensure all edits are related.
3. If any files have been added with fossil add, ensure the makefile is up to date.
4. Ideally, any documentation (Scribble files) should be updated at the same time as the source code. If any .scrbl files have changed, run make scribble to ensure the documentation compiles and is published to this repo.
5. Make sure you’re on the correct branch.

Commit messages

• Commit messages should use the imperative voice.
• Commit messages should be no more than ≈ 50 characters long.
• If more explanation is needed, create a ticket and cross-reference it with the commit message.
• Link a commit to a related ticket by using brackets [ ] containing at least the first 6 digits of the UUID.
• Comments added to tickets in connection with a resolving check-in should describe why the change was made, not how (the code does that part already).