GitHub Package Ideas I Stole

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: tal.galili@gmail.com

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.

Blog post created using the reports (Rinker, 2013) package

Get the .Rmd file here


References

About tylerrinker

I am Literacy PhD student with a bent for the quantitative and a passion for R.
This entry was posted in knitr, package creation, reports, Uncategorized and tagged , , , , , , . Bookmark the permalink.

5 Responses to GitHub Package Ideas I Stole

  1. Bryan Hanson says:

    Excellent suggestions Tyler. I was moving toward some similar things, and studying your repo gave me some additional ideas, so thank you. Now I just need some time!

  2. Tal Galili says:

    Dear Tyler – great list. Thank you for the links and kind words.

    BTW, the NEWS file of Yihui seems to have more steps added to it before it is released as NEWS.md.
    I actually suspect he writes his NEWS file as NEWS.md, and then changes it to .md via his makefile, see here:
    https://github.com/yihui/knitr/blob/889d287b49633c15aade33da4fee9793d376db86/Makefile
    (but for now, I will simply go with your file.copy hack…)

    With regards,
    Tal

    • tylerrinker says:

      Yeah Tal looking at what Yihui has pushed the NEWS.md file is more up to date than the plain text NEWS and the Makefile confirms.

      • Yihui says:

        Yes, my NEWS was generated from NEWS.md via some shell commands in the Makefile. Who cares about NEWS! That is only for R. Everybody should read NEWS.md, which is for humans :)

  3. +1 on the versioning scheme. It’s what we do for Stan. I call the stay-under-1 schemes, like 0.0, 0.1,0.5, 0.9, 0.9.1, …, 0.9.9, … and their ilk, Xeno numbering.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s