# GitHub Package Ideas I Stole

August 31, 2013
By

(This article was first published on TRinker's R Blog » R, and kindly contributed to R-bloggers)

One of my favorite sources of good ideas is looking at the GitHub repositories of others and modeling my repos after the good ideas I see others doing. Here's Steve Jobs on stealing ideas:

In the past few weeks I've spotted three simple things other maintainers are doing that I liked and which I promptly incorporated into my own repos. I wanted to shine a light on those three ideas.

# Versioning Semantics

The first idea comes from Carl Boettiger, the maintainer of the knitcitations (Boettiger, 2013) package. In his NEWS file for knitcitations Carl provides the reader with his versioning semantics as seen below.

Releases will be numbered with the following semantic versioning format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

* Breaking backward compatibility bumps the major (and resets the minor
and patch)
* New additions without breaking backward compatibility bumps the minor
(and resets the patch)
* Bug fixes and misc changes bumps the patch


Until Yihui's blog post I thought 1.0.0 implied maturity. To some maintainers this may be the case but I choose to follow Carl's model and I feel it is important to tell the user of your package what the versioning means. In fact a major version bump may indicate an increased likeliness of bugs, not maturity. To you Carl I say “Well played sir!”

# Contact

The second practice I picked up is Tal Galili's use of a Contact section included in the README.md file of the installr (Galili, 2013) package as seen below.

Contact

You are welcome to:

* submit suggestions and bug-reports at: https://github.com/talgalili/installr/issues
* send a pull request on: https://github.com/talgalili/installr/
* compose a friendly e-mail to: [email protected]
/* <![CDATA[ */
(function(){try{var s,a,i,j,r,c,l,b=document.getElementsByTagName("script");l=b[b.length-1].previousSibling;a=l.getAttribute('data-cfemail');if(a){s='';r=parseInt(a.substr(0,2),16);for(j=2;a.length-j;j+=2){c=parseInt(a.substr(j,2),16)^r;s+=String.fromCharCode(c);}s=document.createTextNode(s);l.parentNode.replaceChild(s,l);}}catch(e){}})();
/* ]]> */



Simple but brilliant. Tal is explicit about where to submit both suggestions and bug reports as a GitHub's issues page often implies just bugs and such, not improvements. Because of the history of R many users will attempt to contact you via email directly, thus you explain the same problem many times rather than answering it once in a public forum. Tal's format is direct yet diplomatic in that it directs the user to co-action rather than asking for fixes (see Yihui's blog post about this). Notice that email is listed as last. This reminds me of my first grade teacher's mantra “Ask three before me.”

# NEWS.md

Last I saw Yihui Xie's use of a NEWS.md file in the knitr (Xie, 2013) package. The typical NEWS file is plain text and boring. The inclusion of a NEWS.md is much prettier to look at and creates a better experience for the package user. Including a NEWS.md merely requires a quick file conversion via:

file.copy("NEWS", "NEWS.md")

I then included NEWS.md in my .Rbuildignore to avoid clogging up CRAN needlessly. To you Yihui I say very nice, high five!

I hope these little stolen bits of goodness are useful to fellow idea thieves. Please be sure to provide feedback in the comments below.

Created using the reports (Rinker, 2013) package

Get the .Rmd file here