forked from hadley/r-pkgs
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathrelease.rmd
195 lines (125 loc) · 9.66 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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
---
title: Releasing a package
layout: default
output: bookdown::html_chapter
---
# Releasing a package {#release}
Once you are confident that your package is reliable and does what it claims, you should explicitly release it. This basically means given it an explicit version number that people can refer it. You have two basic choices for where to release it:
* On CRAN, which is a formal and rigorous process. It can be frustrating,
but is important if you want your package to be used by the widest
number of people.
* On github, which is informal and simple. You'll get more out of it by
using a standard procedure and taking advantage of github releases.
Important files:
* the `NEWS` file describes the changes in each version of the package. Using
the standard R format will allow you to take advantage of many automated
tools for displaying changes between versions.
* the `README.md` file gives a general overview of your package, including why
it's important. This text should be included in any package announcement, to
help others understand why they might want to use your package.
Where to release?
## `README.md`
The `README.md` file lives in the package directory. It should be fairly short (3-4 paragraphs) and answer the following questions:
* Why should someone use your package?
* How does it compare to other existing solutions?
* What are the main functions?
If you're using github, this will appear on the package home page. I also recommend using it when you announce a new version of your package.
See [markdown](#markdown) for more details on markdown.
## `NEWS`
The `NEWS` file should list all changes that have occurred since the last release of the package.
The following sample shows the `NEWS` file from the `stringr` package.
stringr 0.5
===========
* new `str_wrap` function which gives `strwrap` output in a more
convenient format
* new `word` function extract words from a string given user defined
separator (thanks to suggestion by David Cooper)
* `str_locate` now returns consistent type when matching empty string
(thanks to Stavros Macrakis)
* new `str_count` counts number of matches in a string.
* `str_pad` and `str_trim` receive performance tweaks - for large vectors
this should give at least a two order of magnitude speed up
* str_length returns NA for invalid multibyte strings
* fix small bug in internal `recyclable` function
`NEWS` has a special format, but it's not well documented. The basics are:
* The information for each version should start with the name of the package
and its version number, followed by a line of `=`s.
* Each change should be listed with a bullet. If a bullet continues over
multiple lines, the second and subsequent lines need to be indented by at
least two spaces. (I usually add a blank line between each bullet to make it
easier to read.)
* If you have many changes, you can use subheadings to divide them into
sections. A subheading should be all upper case and flush left.
* I use markdown formatting inside the bullets. This doesn't help the
formatting in R, but is useful if you want to publish the `NEWS` file
elsewhere.
You can use `devtools::show_news()` to display the `NEWS` using R's built-in parser and check that it appears correctly. `show_news()` defaults to showing just the news for the most recent version of the package. You can override this by using argument `latest = FALSE`.
Another option is to write `NEWS.md`.
* Can't include in package (needs to be in `.Rbuildignore`), and so not
on CRAN.
* Easier to read on github
* Easier to copy-and-paste into github releases.
## Version numbers {#version}
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 Versioning](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 a sub-patch version number of 9xxx, as in 1.9.0.9000, 1.9.0.9001, and so on. Whenever an important feature is added or a bug is fixed, increment the number. This makes it clear for users that they're using a development version of the package, as opposed to a formally released version, and it also makes it easy for people to see when their development version is out of date.
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. If you fix a bug that people are depending on, then it will feel like an API breaking change to them.
## Publishing on Github
Managing releases.
## Publishing on CRAN
Once you have passed the check process, you need to upload your package to CRAN. This is a relatively complicated multi-step process:
1. Build a package bundle with `build()`.
1. Upload to <http://cran.r-project.org/submit.html>
1. Confirm submission email
1. Wait for response.
Instead, I recommend using `devtools::release()` which asks a number of questions to make sure that you're ready, then builds, uploads and submits for you.
* Adding extra questions
* Comments to CRAN
On failure, make the suggested changes, update `cran-comments.md` describing what you did and why, and re-run `release()`. CRAN prefers you to not respond to their emails unless discussion is required.
Submitting to CRAN is frustrating, but you're not alone. Even R-core members who submit packages to CRAN have to go through the same gruelling process, and CRAN is no friendlier to them. Try not to get upset by the feedback. Ignore any ad hominen attacks, and simply respond to the technical comments. Unfortunately there is no recourse, so you just have to put up with it.
Devtools comes with a guarantee: If someone from CRAN is annoyed at your because of something that devtools does worng, I will send you a hand-written apology card. Please send me an email with your address.
### CRAN policies
[CRAN policies](http://cran.r-project.org/web/packages/policies.html).
Most important points:
* Must pass `R CMD check` without errors, warnings and ideally notes. If there
are notes that you do not believe are important, it is almost always easier
to hack around them than to persuade CRAN that they're ok.
* Must have clearly identified IP holders, have open source license (so CRAN
can distribute it) and not include any binary executables.
* Maintainer email address must be correct. CRAN will make no effort
to contact apart from through this address. Make sure it's something
that's likely to be around for a while
* Must not be more than 5 megs.
* Packages shouldn't make external changes without explicit user permission.
Don't write to the file system, change options, install packages, quit R,
send information over the internet, open external software, etc.
* You must not use `:::`
## Post-release
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. If you use github, use github releases - copy and paste
the relevant portion of the NEWS file (converting to markdown if needed).
* bump version in `DESCRIPTION` and `NEWS` files. Use `.9000` prefix to
indicate that it's a development version.
## Publicising
Then you need to publicise your package. This is vitally important - for your hard work to be useful to someone, they need to know that it exists!
* Write release announcement. 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`.
* You can also send an email to `[email protected]`, but there
a number of rules about how often you're allowed to post, and it's not
that friendly (also not clear how big the reach is.)
* 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.