jxson

Synopsis

At the top of the file there should be a short introduction and/ or overview that explains what the project is. This description should match descriptions added for package managers (Gemspec, package.json, etc.)

Code Example

Show what the library does as concisely as possible, developers should be able to figure out how your project solves their problem by looking at the code example. Make sure the API you are showing off is obvious, and that your code is short and concise.

Motivation

pbrisbin

I personally prefer [Semver][]. I think it's reasonable, simple, and makes sense. But as a good Haskell citizen, I'd like to be [PVP][]-compliant as well. Here is a bit of a graphic showing how the two systems are almost the same:

PVP:            A . B     . C     . ...
Semver:             Major . Minor . Patch
                    ^       ^       ^
                    |       |       |
                    |       |       ` increment for other changes
                    |       |
                    |       ` increment on non-breaking change

pbrisbin

Using <details> in GitHub

Suppose you're opening an issue and there's a lot noisey logs that may be useful.

Rather than wrecking readability, wrap it in a <details> tag!

<details>
 <summary>Summary Goes Here</summary>

jakobhellermann

#!/bin/bash

if [[ $(git diff --stat) != '' ]]; then
  echo 'git has uncommit changes, please commit as this tool can break stuff'
  exit
fi

echo "warning: this code isn't very well tested"
read -p "Press enter to continue: "