Bioconductor
Document steps for new package releases
After #28 is complete, let's be sure to document the exact steps for a new release much like we have for utils-java
For example, click on the RStudio "check" button which takes care of running the following:
roxygen2::roxygenize('.', roclets=c('rd'))
R CMD build api-client-r
R CMD check --as-cran GoogleGenomics_0.1.2.tar.gz
and then for BioConductor to pick up the release do . . .
Sure. I will add that documentation in a separate RELEASE file or maybe include it in CONTRIBUTING.
if it's possible to re-run everything from the command line (and that invocation could be included) it will be easier to contribute patches, etc. All the Roxygen/autodoc stuff is nice but a little intimidating to persons that do not use that exact setup. (not that I can blame my current inactivity on this!)
For example, I've submitted PRs in the past and explicitly avoided writing additional documentation, as the scary remarks suggested it would perish, like so many tears in the rain.
Similarly, since the internal google-rlint contains nuclear launch codes and the President's luggage password, it wouldn't do to release it publicly... therefore, lintr might be preferable for contributors ;-)
Anyways. I'll get back to painting my bikeshed.
--t
On Wed, Mar 25, 2015 at 11:06 AM, Siddhartha Bagaria < [email protected]> wrote:
Sure. I will add that documentation in a separate RELEASE file or maybe include it in CONTRIBUTING.
— Reply to this email directly or view it on GitHub https://github.com/googlegenomics/api-client-r/issues/35#issuecomment-86152461 .
This is the first time I am hearing a bike-shedding reference in a review process. :+1: I agree with you Tim on the points you made.
The entire process can be fairly automated including the roxygen stuff. And now that I used jimhester's lintr tool, I am going to move to using that for this package. In fact, the lintr run will be part of unit tests, and so Travis will make it difficult to submit your patch without lintr compliance.
Documentation that is not close to source code does indeed tend to get outdated and perish. Also why we use roxygen instead of separately written man pages. So this will be a fairly small section in the CONTRIBUTING file. Basically, I will add just one more command there to the existing commands, one that will update man pages based on source code doc by running roxygen.
I will most likely set up a bridge between github and bioc so pickup by bioconductor will be automatic. I will add a note about version number increment to actually publish an updated package to the devel repository.
Oh man, I haven't laughed so hard in some long time! Tim, you crack me up so much! Please post more often - I need a refreshing perspective :)
I agree with Tim on this one - help should be super-simple, already included/provided and everything complex should happen in the background. Folks should just focus on using the API the most, rather than building the doc that gives them the help to use the API.
~p
