-
-
Notifications
You must be signed in to change notification settings - Fork 1
/
releases.qmd
192 lines (149 loc) · 8.23 KB
/
releases.qmd
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
---
title: "Release Process for Workbench Packages"
---
## Background
The workbench contains three main packages:
- [{sandpaper}]\: user interface and workflow engine
- [{pegboard}]\: parsing and validation engine
- [{varnish}]\: HTML templates, CSS, and JS elements
Each of these packages are available on the [Carpentries R-Universe][r-universe]
and new versions are checked for hourly. This allows folks to get up-to-date
versions of The Workbench packages built for their system without running out
of GitHub API query attempts.
In order to maintain quality, packages are only sent to the R-Universe if they
have been formally released on GitHub ([as specified in the packages.json
configuration
file](https://github.com/carpentries/universe/blob/0c330a1e8f0337de483144fece37c2710af6f4df/packages.json#L16-L33)).
This allows us to incrementally add new experimental features without changing
the stable deployments.
## Versioning
The workbench is built using very basic semantic versioning using the
`X.Y.Z[.9000]` pattern.
[`X`]{#major}
: **Major version number** this version number will change if there are
significant breaking changes to any of the user-facing workflows. That is, if
a change requires users to modify their scripts, then it is a breaking change.
_For example:_ at this time of writing, `{pegboard}` is at version 0.7.0, for
which the `Lesson` object assumes a Jekyll lesson by default. If we were to
change this to assume a sandpaper lesson by default, then this would be a
breaking change because anyone who is using `Lesson$new()` will now need to
use `Lesson$new(jekyll = TRUE)`.
[`Y`]{#minor}
: **Minor version number** this version number will change if there are new
features or enhanced behaviors available to the users in a way that _does not
affect how users who do not need the new features use the package_. An example
of this is `{pegboard}` version 0.7.0 introduced processing of child
documents. If the lesson has no child documents, then it is processed as
expected, but if the child documents exist, then they are additionally
processed and validated.
[`Z`]{#patch}
: **Patch version number** this version number will change if something that
was previously broken was fixed, but no new features have been added. An
example of this is in [`{sandpaper}` version
0.13.3](https://github.com/carpentries/sandpaper/releases/tag/0.13.3) where
there were two bugfixes that affected links to setup page sections and 404
page rendering that otherwise did not add any new features.
[`9000`]{#dev}
: **Development version indicator** this indicates that the version of
{sandpaper} on GitHub is in development and not yet released. This indicator
is always appended to the current release number and should be between 9000
and 9999. For example, you the development version indicator for the version
of sandpaper after 0.13.2 is 0.13.2.9000. This particular version resulted in
a bump to 0.13.3, but it could also have resulted in 0.14.0 or 1.0.0. It has
not been extensively used in the past, but it is quite useful for tracking
incremental changes with different bugfixes and features that may appear. When
this development version indicator exists, the documentation site will have an
extra `dev/` directory that contains the upcoming changes so that we can
continue to develop the workbench without disrupting the regular documentation
flow.
## Release Process
::: {.callout-warning}
### Non-urgent releases only
This release process assumes that we have accumulated bugfixes and/or features
in the `main` branch, which we are ready to release. If you have a bug that
needs to be patched _immediately_ and you have new features in the main branch
that are not yet released, then you should [create a hotfix](hotfixes) instead.
:::
When a package is ready for release we use the following checklist:
- [ ] Create a new branch from `main` called `release-X.Y.Z`
- [ ] Update version number in DESCRIPTION and check that the `Remotes:` is
up-to-date
- [ ] Add NEWS for the changes in this version
- [ ] commit, push changes, and create pull request
- [ ] check the pull request against the [workbench integration
test](https://github.com/carpentries/workbench-integration-test#readme)
- [ ] Merge the pull request when checks pass
- [ ] add new signed tag with the name "<package> X.Y.Z" and push
```bash
# example: create a signed (-s) tag for sandpaper 3.3.3
git tag -s 3.3.3 -m '<short explanation of what changed>'
git push --tags
```
- [ ] create a release on github from the new tag
::: {.callout-note}
Zhian likes to create tags via the command line because he has set up his git
configuration to use [a gpg signature](https://www.garrickadenbuie.com/blog/signed-verified-git-commits-keybase-rstudio/#fnref3)
so the tags and the releases are both verified.
:::
The last two items can be achieved in a single step with the [github
cli](https://cli.github.com/) with the command `gh release create X.Y.Z` for
the version number
```bash
gh release create 3.3.3
# ? Title (optional) sandpaper 3.3.3
# ? Release notes [Use arrows to move, type to filter]
# Write my own
# > Write using generated notes as template
# Leave blank
```
Selecting "Write using generated notes as a template" opens an editor and
populates it with the pull requests that have been accepted since the last
release.
Once the release is created on GitHub, then the package will be available on
the R-Universe in about an hour or less.
## Release Timeline
In the early days of The Workbench, the release process was ad-hoc because the
number of users was low, but now that the entire community is using it, it is
important to set expectations and properly communicate changes to the users.
For [patch relases](#patch), these releases should continue to happen ad-hoc
because, by definition, these releases only fix bugs and do not add new
features.
The release timelines are based on two assumptions:
1. a M--F workweek (i.e. NEVER release on a Friday unless you like working on
the weekend)
2. All lesson builds and updates happen every Tuesday at 00:00 UTC (packages for
R-based lessons are updated on the _first_ Tuesday)
### Minor Feature Updates
For releases that add new non-breaking features which bump the [minor
version](#minor), it is important to alert the community a couple of days in
advance of the release so they have a chance to give feedback before the
release. Thus, I propose the following timeline:
1. **Friday (drafting)**: Members of Workbench Maintainer Group draft
communications describing new features
2. **Monday (communications)**: Communications describing new features sent to
relevant communities (maintainers/trainers/instructors, depending on
feature)
3. **Wednesday (release)**: New version of Workbench package(s) released
We release on Wednesday in order to give enough time for the communications to
sink in _and_ give enough time for us to release patches to the release before
all lessons get rebuilt.
### Breaking Changes
If there are breaking changes, it is important to give the community enough time
to adapt and to offer them a path forward to fix their workflows. Depending on
how drastic the change is, it may be important to conduct beta testing to
ensure that the change doesn't contain any unforseen bugs and, importantly, that
it _improves the workflow for the audience over doing nothing at all_.
The Beta Phase of The Workbench is an extreme version of this, but it _is_
important, because [major version changes have real-world
consequences](https://github.com/dwinter/mmod/issues/2) that you want to avoid
as much as possible.
The release should still happen on a Wednesday, but the communications aspect
should be timely, specific, targeted, and repeated. It may be that you have to
communicate about the change one week, one month, or even one quarter ahead of
the release. In a volunteer community, you will end up in situations where
people are checked out for months at a time and will see everything changed, so
please do take care with the communications and changes.
[{varnish}]: https://carpentries.github.io/varnish/
[{pegboard}]: https://carpentries.github.io/pegboard/
[{sandpaper}]: https://carpentries.github.io/sandpaper/
[r-universe]: https://carpentries.r-universe.dev/