forked from hadley/adv-r
/
Release.rmd
76 lines (47 loc) · 5.35 KB
/
Release.rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
---
title: Releasing a package
layout: default
---
# Releasing a package
## Checking
* from within R, run `roxygenise()`, or `devtools::document()` to update
documentation
* from the command line, run `R CMD check`
Passing `R CMD check` is the most frustrating part of package development, and it usually takes some time the first time. Hopefully by following the tips elsewhere in this document you'll be in a good place to start – in particular, using roxygen and only exporting the minimal number of functions is likely to save a lot of work.
One place that it is frustrating to have problems with is the examples. If you discover a mistake, you need to fix it in the roxygen comments, rerun roxygen and then rerun `R CMD check`. The examples are one of the last things checked, so this process can be very time consuming, particularly if you have more than one bug. The `devtools` package contains a function, `run_examples` designed to make this somewhat less painful: all it does is run functions. It also has an optional parameter which tells it which function to start at - that way once you've discovered an error, you can rerun from just that file, not all the files that lead up to.
## Version numbers
The version number of your package increases with subsequent releases of a package, but it's more than just an incrementing counter -- the way the number changes with each release can convey information about what kind of changes are in the package.
An R package version can consist of a series of numbers, each separated with "." or "-". For example, a package might have a version 1.9. This version number is considered by R to be the same as 1.9.0, less than version 1.9.2, and all of these are less than version 1.10 (which is version "one point ten", not "one point one zero). R uses version numbers to determine whether package dependencies are satisfied. A package might, for example, import package `devtools (>= 1.9.2)`, in which case version 1.9 or 1.9.0 wouldn't work.
The version numbering advice here is inspired in part by [Semantic Versionsing](http://semver.org) and by the [X.Org](http://www.x.org/releases/X11R7.7/doc/xorg-docs/Versions.html) versioning schemes.
A version number consists of up to three numbers, _<major>_._<minor>_._<patch>_. For version number 1.9.2, 1 is the major number, 9 is the minor number, and 2 is the patch number. If your version number is 2.0, then implicit patch number is 0.
As your package evolves, the way the version number changes can reflect the type of changes in the code:
* The major number changes when there are incompatible API changes.
* The minor number changes when there are backward-compatible API changes.
* The patch number changes with backwards-compatible fixes.
* Additionally, during development between released versions, the package has has a sub-patch version number of 99, as in 1.9.0.99. This makes it clear for users that they're using a development version of the package, as opposed to a formally released version.
Remember that these are guidelines. In practice, you might make changes that fall between the cracks. For example, if you make an API-incompatible change to a rarely-used part of your code, it may not deserve a major number change.
## Publishing on CRAN
Once you have passed the checking process, you need to upload your package to CRAN. The checks will be run again with the latest development version of R, and on all platforms that R supports - this means that you should be prepare for more bugs to crop up. Don't get excited too soon!
* update `NEWS`, checking that dates are correct. Use `devtools::show_news` to
check that it's in the correct format.
* `R CMD build` then upload to CRAN:
`ftp -u ftp://cran.R-project.org/incoming/ package_name.tar.gz`
* send an email to `cran@r-project.org`, using the email address listed in the DESCRIPTION file. An example email would be something like: Hello, I just uploaded package name to CRAN. Please let me know if anything goes wrong. Thank you, Me. The subject line should be `CRAN submission PACKAGE VERSION`, this helps the CRAN maintainers keep track of the different submissions.
Once all the checks have passed you'll get a friendly email from the CRAN maintainer and you'll be ready to start publicising your package.
## Publicising
Once you've received confirmation that all checks have passed on all platforms, you have a couple of technical operations to do:
* `git tag`, so you can mark exactly what version of the code this release
corresponds to
* bump version in `DESCRIPTION` and `NEWS` files
Then you need to publicise your package. This is vitally important - for you hard work to be useful to someone, they need to know that it exists!
* send release announcement to `r-packages@stat.math.ethz.ch`. A release
announcement should consist of a general introduction to your package (i.e.
why should people care that you released a new version), and as well as
what's new. I usually make these announcements by pasting together the
package `README` and the appropriate section from the `NEWS`.
* announce on twitter, blog etc.
* Finally, don't forget to update your package webpage. If you don't have a
package webpage – create one! There you can announce new versions, point to
help resources, videos and talks about the package. If you're using github,
I'd recommend using [github pages](http://pages.github.com/) to create the
website.