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]

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

References

• C. Boettiger, (2013) knitcitations: Citations for knitr markdown files. http://CRAN.R-project.org/package=knitcitations
• Tal Galili, (2013) installr: Functions for updating and installing a new version of R and other software – from R. http://CRAN.R-project.org/package=installr
• Tyler Rinker, (2013) reports: Package to asssist in report writing. http://github.com/trinker/reports
• Yihui Xie, (2013) knitr: A general-purpose package for dynamic report generation in R. http://yihui.name/knitr/