Contribution Guidelines

Don't be shy! Most of my repos are open to contribs and suggestions (even style/format requests)

I assume you've (mostly) read these:

• Learn Git
• Basic GH docs

For anything not specified here, use common-sense and follow "best practices"

Issues & Pull Requests

• Any PR patch-size is fine, but small PRs are preferred because they're easier/faster to review. Big PRs are dreams and nightmares simultaneously
• I prefer rebasing rather than merging. Update your PR branch by rebasing. Only merge if there's a complicated merge-conflict.

Tip

You can update with Git (CLI) alone, but your local repo must have both remotes. Example:

git fetch upstream && \
git rebase upstream/main && \
git push --force-with-lease

Or you can update the remote before your local branch:

gh pr update-branch --rebase && \
git pull -r

• If your PR has too many commits, I'll be tempted to squash it. If you keep the log tidy, then I'll try to preserve your commits.
• If my review requested changes, I suggest converting to draft while you're applying them, then mark as "ready" after pushing. This way, you can notify me without commenting.

Style & Formatting

• Why I prefer tabs over spaces
  • Alexander Sandberg advocates for accesibility
  • Lea Verou outlines several reasons
• Please use -1 (relative, clamped to 0) level of indent in JSON. This is to reduce redundancy. Example:

{
	"❌": "no"
}
{
"✅": "ok"
}

That rule only applies if the entire file is just 1 object (array or dictionary, nested or flat). IOW, JSONL is exempt, for better readability. These rules also extrapolate to Lua-Table-Notation (LTN or "LON"), and any other format where there's a "base level" of indentation.

• If you add a subjective comment, surround it within quotes, and include your name (any: display-name, username, etc...). Example:

# "I couldn't find a better alternative" @ghost

This is to avoid confusion (for future readers) caused by unintentional impersonation. This way, everyone knows who said what, without git blame. Objective comments (like # this X implementation is faster than Y) don't need usernames

• Use spaced comments for non-code. Examples:

# ✅
#❌
#0 + 0 # ✅
# 0 + 0 #❌

• In case of doubt, search for patterns in the way the code is written, and please try to replicate those patterns, for consistency
• Read my .files, for more info
• See also these naming guidelines. Some of my repos are not fully compliant, yet.