jtleek / rpackages Goto Github PK

sorry I do not have time to write a formal pull request (some points are not for pull requests, either), but just some feedback and comments for now:

• GIT: always use a GIT GUI; almost never git add *; I use Ubuntu, so apt-get install git-gui first, and git gui is how I work every day; I use the GUI to select minimal sets of lines of changes to commit instead of just committing everything; then
  • explain in each commit what you did, and sometimes explain why it must be done
  • if a commit fixes a Github issue, write fixed #n and Github will close that issue automatically when you push
  • if you fixed a bug, write a test accordingly, so eventually for all bugs and fixes, you know the full history, e.g. yihui/knitr#636
• the only GIT commands that I use are git clone (once), git rebase -i (occasionally), git pull --rebase, and sometimes git checkout -b (only in case of collaboration); for the rest of jobs like git commit and git push, etc, I always use the GUI
• I find Authors@R very useful for several reasons
  • it generates Author and Maintainer automatically when you R CMD build
  • consequently, citation(pkg, auto=TRUE) generates a clean BibTeX entry; if everyone uses this, I would not have to do this ugly hack: https://github.com/yihui/knitr/blob/master/R/citation.R
• some software communities hates GPL and prefers more permissive licenses like MIT; I think they have a point (in the academic environment, GPL is often not an issue, but in the industry, GPL can be too restrictive)
• we (RStudio) have been looking into the possibility of making "reproducible" shiny apps, e.g., you can provide a list of input values or save the current state in a "bookmark", and the app can reproduce itself later

Is tidyr available for R version 3.0.3? I cannot do lesson 3 on swirl in the course "Getting and Cleaning Data".

Thanks for the awesome package writing guide.
You suggest

To use the testthat package you will put a file called test-area-packagename.R in the > inst/tests directory, where area is the name of the broad class of functions you are
testing. Then add another file called run-all.R in the same directory.

However, I noticed that this wasn't automatically running the tests when I ran R CMD CHECK in RStudio. I noticed that Hadley puts run-all.R in tests (e.g., stringr and puts the actual tests in inst/tests). When I did that, I had automated tests with R CMD CHECK.

Hi Jeff,

I'm not sure how it plays out with R/Bioconductor/CRAN but I've found that the Semantic Versioning Policy is extremely useful.

The primary difference between SemVer and what you've prescribed here is the notion of a "public API" upon which those who build atop your package depend. This dovetails neatly with the need for documentation as once you've established version 1.0.0 and solidified your public API, you really commit to using the version number to indicate to your users whether the changes you're making are likely to break their code.

The reason I bring this up is not that it's significantly different than what you wrote, but instead just to stress the notion of a public API. Clearly stating this helps to think about how your packages are structured and also allows you develop a "private API" which can change more quickly without affecting major version numbers. This is useful for continued personal experimentation or slowly adding new functionality to the public API in a backwards compatible fashion.

This is somewhat covered by the documentation sections (and specifically the @export annotations), but I think the concept itself is worth stressing. In a package that really gets used a lot and built upon, careful choice of the public API and maintaining it responsibly is a very definite design task. Spending a little time before v1 working it out can pay out exponentially down the road.

In the body, you mention having an Rmd file in inst/doc, and using the BiocStyle latex styles.

If you are going to use Rmd files, you will be producing HTML vignettes, unless you plan to do markdown to latex in the end using some kind of makefile and pandoc. So I am guessing you actually meant to have an Rnw file.

Also, as of the latest version of R, the place to put the vignette source is in packagename/vignettes, and let the build take care of putting them in inst/doc/, or do build_vignettes from the command line.

Do the same as in jtleek/datasharing#154 to get http://lcolladotor.github.io/rpackages/

Jeff:

Appreciated your advice. However you have a malformed link pointing to GitHub Flow in your sentence
"In particular, github flow is an excellent way to manage contributions,"

you don't want your github address pre-appended onto http://scottchacon.com/2011/08/31/github-flow.html