forked from carpentries/workbench
-
Notifications
You must be signed in to change notification settings - Fork 0
/
beta-phase.qmd
328 lines (242 loc) · 16.7 KB
/
beta-phase.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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
---
title: "beta phase of The Carpentries Workbench"
subtitle: "2022-12-12 to 2022-04-03"
---
## What is the Workbench beta phase?
The Carpentries Workbench, first released in January 2022, has been running
without issue for several months with several early adopters, who have all
contributed to its improvement from their feedback. It is now at the stage
where we are confident that it is in a stable condition to be used for
Carpentries Lessons as a whole. Of course, with over 100 maintainers and even
more instructors, making a sudden change has the potential to be massively
disruptive.
Instead, we are slowly releasing The Workbench in **three stages**
over a **16 week period during which there will be _parallel websites_ showing
two versions of the same lesson[^parallel-nightmares].** For example, when you
visit `https://datacarpentry.org/R-ecology-lesson`, there will be a banner at
the top of every page that will give a link to the beta version of the lesson
(under `https://preview.carpentries.org/`) and the dates the styles version
will be deprecated and finally superseded.
<iframe width="100%" height="315" src="https://www.youtube-nocookie.com/embed/x7tETGpF3-4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
This slow progression is designed to allow community members to familiarlize
themselves with the new format and to build expertise within the community for
May 2023 when the infrastructure is formally released.
The three stages are called ["pre-beta"](#pre-beta), ["beta"](#beta)[^beta], and ["pre-release"](#pre-release).
If you would like to participate in the beta phase, you can
- [find out more about our workbench through our Resource Guide](index.html#resources),
- **[introduce yourself](https://github.com/carpentries/workbench/discussions/1)**, and
- [give feedback via GitHub Discussions](https://github.com/carpentries/workbench/discussions/)
[^parallel-nightmares]: It will be mostly the same content, save for small
changes as described in the different stages.
[^beta]: Note, this is NOT the same thing as an in-development lesson being in
Beta.
{
fig-alt="Diagram of three phases of the beta release. At the top is box
labelled 'current' that contains a GitHub logo, a cartoon of a lesson page.
Below is a box labelled 'Pre Beta' with the same contents as the box above plus
an additional GitHub logo in blue with a camera above it (to indicate a
snapshot) and a new cartoon of a lesson page with a padlock over it. There is a
clock indicating a timeframe of four weeks. The next box below is labelled
'Beta'. The GitHub logo has become blue and there is a lightning bolt and a
line connecting it to the previous logo, indicating that a transformation
happened. A smaller, grey GitHub logo is adjacent with a lock over it,
indicating that it is archived. The old lesson page now has a lock and
information symbol above it. The new lesson page does not have any symbols
above it. The timreframe is 6 to 8 weeks. The final box is titled 'Release
Candidate' and has a single blue GitHub logo, a faded old lesson page, and a
new lesson page with a timeframe of 6 months"}
### **pre-beta** (two repos, two sites) {#pre-beta}
Lessons in this stage will have a workbench version of the lesson live in a
separate repository in a [sandbox GitHub
organisation](https://github.com/fishtree-attempt)[^pun]. This version will be a
**snapshot from the date of the pre-beta version**. Any changes made to the
snapshot will appear on the beta website, but will disappear as soon as the
lesson enters beta. Maintainers are encouraged to clone this snapshot
repository and try it out by creating pull requests that change content.
[^pun]: The sandbox organisation is called "Fish Tree Attempt", which is a pun
on Carpentry: *carp*---fish, tree---*ent* (after Tolkien), attempt---*try*
::::: {#pre-beta-tasks .callout-note}
### Tasks to try
The purpose of the pre-beta stage is to make sure maintainers are comfortable
with working on the lesson. Anything that happens on the [sandbox
repository](https://github.com/fishtree-attempt) is not permanent. Below is a
list of tasks for different members of the community to try.
As always, please **provide feedback in
our [< 1 minute survey](https://carpentries.typeform.com/to/KRBl4IZM)**
::: {.panel-tabset}
#### Maintainers
During this time, you should take the time to merge or resolve any open PRs in
your lesson. And yes, this is a big task and it is helpful to [remember how to
say 'no'](https://opensource.guide/best-practices/#learning-to-say-no) in a way
that respects the contributor’s time and effort. *If you feel like you need help
with a particular PR, please contact Zhian and he will help craft a response.*
- clone the lesson and build it locally (see the [setup instructions](https://carpentries.github.io/sandpaper-docs#setup))
- merge one of the [automated workflow update PRs](https://carpentries.github.io/sandpaper-docs/pull-request#automated-pull-requests) that is opened by [@carpentries-bot](https://github.com/carpentries-bot)
- review a PR that includes some failing accessibility checks
- (R lessons only) review a PR using the [preview of rendered changes](https://carpentries.github.io/sandpaper-docs/instructor/pull-request.html#reviewing-a-pull-request)
- create an [inline instructor note](https://carpentries.github.io/sandpaper-docs/instructor/episodes.html#instructor-notes) from existing instructor notes
- fix a simple typo in a lesson---perhaps in a relatively non-obvious location e.g. in the setup instructions
- fix some broken syntax in a lesson
- write a link from one episode to another in the same lesson
- trigger a rebuild of the lesson from GitHub Actions
#### Instructors
Browse the lesson and give feedback on your impressions. Is everything where you
expect it to be?
#### Contributors
Make a contribution to an episode! Click on the "Edit this page" button and make
a change.
:::
:::::
### **beta** (one repo using the workbench, two sites) {#beta}
Lessons in this stage will undergo a lesson release of the styles version and a
snapshot of the repository, including issues and pull requests, will be
archived. The default branches (`gh-pages` and `main`) will be renamed and a
transformation[^modify] of the default branch will be inserted as `main`:
| branch | transformation | new name |
| ------ | -------------- | -------- |
| `gh-pages` | none | `legacy/gh-pages` |
| `main` | none | `legacy/main` |
| [default] | [remove styles commits](https://github.com/carpentries/lesson-transition#motivation); transform syntax to Workbench | `main` |
The default lesson URL will still be served from the `legacy/gh-pages` branch
during this period. **All new changes to the lesson will be made to the
workbench version.**
::::: {#beta-tasks .callout-note}
### Tasks to try
As always, please **provide feedback in
our [< 1 minute survey](https://carpentries.typeform.com/to/KRBl4IZM)**
::: {.panel-tabset}
#### Maintainers
<iframe width="100%" height="315" src="https://www.youtube-nocookie.com/embed/161YyNjbYrQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
Before this stage can happen, you must **merge or resolve any open PRs in your
lesson.** *If you feel like you need help with a particular PR, please contact
Zhian and he will help craft a response.*
During this stage, you are working on the lesson as you would normally, which
means to address any issues or pull requests that come in and improve the
lesson. In addition, I would recommend to continue to do the things you were
doing during the [pre-beta stage](#pre-beta), but first:
1. Update your local version of the lesson ([instructions to update](#updating-clone))
2. Re-fork the lesson if you have a fork (see the [instructions in the FAQ](faq.html#update-fork-from-styles))
#### Instructors {#pre-beta-instructor}
Browse the lesson and give feedback on your impressions. Is everything where you
expect it to be?
Now that the lesson source is in a permanent stage, **add an inline instructor note**.
Click on the "Edit this page" button in any episode and make a change.
#### Contributors {#pre-beta-contributor}
Make a contribution to an episode! Click on the "Edit this page" button and make
a change.
:::
:::::
::: {#updating-clone .callout-tip appearance='simple'}
#### Updating your local clone
During this phase, you will need to take care to bring in the changes to your
local clone because they WILL be different. Details can be found in [The Lesson
Transition repository](https://github.com/carpentries/lesson-transition#keeping-your-clone-up-to-date):
::: {.panel-tabset}
##### Quck and Dirty
The easiest way is to get the updates and avoid dreaded merges is to use the
[burn it all down approach](https://happygitwithr.com/burn.html). For those who
are more confident in their git skills, read on.
##### via Git: Markdown Lessons
The general strategy is the same as when someone changes the name of their
default branch: rename your local branch, fetch the changes, and set the right
branch to track upstream:
In your lesson, use these commands. DO NOT PULL FIRST.
```bash
git checkout gh-pages # make sure you are gh-pages
git branch -m gh-pages legacy/gh-pages # rename the gh-pages branch to legacy
git fetch origin # fetch changes from GitHub
git branch -u origin/legacy/gh-pages legacy/gh-pages # make sure your legacy branch tracks
git checkout main # switch to the brand-new main branch
git remote set-head origin -a # set main branch to be your local default
```
##### via Git: R Markdown Lessons
The general strategy is the same as when someone changes the name of their
default branch: rename your local branch, fetch the changes, and set the right
branch to track upstream:
In your lesson, use these commands. DO NOT PULL FIRST.
```bash
git checkout main # make sure you are on main
git branch -m main legacy/main # change 'main' to legacy
git checkout gh-pages # switch to gh-pages
git branch -m gh-pages legacy/gh-pages # rename the gh-pages branch to legacy
git fetch origin # fetch changes from GitHub
git branch -u origin/legacy/main legacy/main # make sure your legacy branches track
git branch -u origin/legacy/gh-pages legacy/gh-pages
git checkout main # switch to the brand-new main branch
git remote set-head origin -a # set main branch to be your local default
```
:::
:::
[^modify]: For details of what will happen to the files and syntax during the
transition, see [The Transition Guide](transition-guide.html). During the
transformation, we will also excise the commits from styles, which necessarily
rerwite the history of the lesson, while **preserving the commits from lesson
content**. This move has two benefits:
1. The list of committers on the lesson will better reflect the actual lesson
contributors rather than the contributors to the template.
2. Lessons will be reduced in size so that downloading them and contributing to
them will be easier. There _is_ precedence for this: When Software Carpentry
moved its lessons from the original
[swcarpentr/bc](https://github.com/swcarpentry/bc) monorepo, they excised the
commits related to each lesson from the repository, but preserved the history.
Maintainers will continue to work on this workbench version of the lesson.
### **pre-release (release-candidate)** (one repo using workbench, one site) {#pre-release}
The styles version of the lesson (in the `legacy/` branches) will be removed,
the default version of the lesson will switch to The Workbench, and the
workbench-beta website will redirect to the live lesson.
## Lessons currently in the beta phase
Maintainers of the following lessons have agreed to use their lessons to test
out the beta phase of The Carpentries Workbench: If you want to preview these
lessons, please visit the lesson, browse around and then **provide feedback in
our [< 1 minute survey](https://carpentries.typeform.com/to/KRBl4IZM)**
| Lesson | Workbench URL |
| -------------------------------------------------------- | ------------------------------------------------------------ |
| R for Social Scientists | <https://preview.carpentries.org/r-socialsci> |
| Introduction to Geospatial Raster and Vector Data with R | <https://preview.carpentries.org/r-raster-vector-geospatial> |
| Instructor Training | <https://preview.carpentries.org/instructor-training> |
| Análisis y visualización de datos usando Python | <https://preview.carpentries.org/python-ecology-lesson-es> |
These lessons are all in the [**first (pre-beta) stage**](#pre-beta) and will
transition to the [second (beta) stage](#beta) on **2023-02-03**.
### Timeline
```{mermaid}
gantt
dateFormat YYYY-MM-DD
axisFormat %d %b
title Schedule For Lessons in Workbench Beta
beta phase Start :milestone, 2022-12-12,
Pre Beta : dcre-pb, 2022-12-12, 56d
Beta : dcre-b, after dcre-pb, 56d
Pre-release :milestone, crit, after dcre-b
```
These are the official Carpentries lessons that have entered the beta phase. Note
that three out of the seven participated in the early stages of the beta phase,
but were unable to continue due to extenuating circumstances. 2022 was a tough
year for many people and participating in the beta phase was a voluntary act for
our volunteer maintainers.
I am grateful for all of the maintainers who have participated in any stage of
the beta phase. All of the contributions from the maintainers of these lessons
have helped bring stability and refinement to The Carpentries Workbench.
- [datacarpentry/r-socialsci---R for Social Scientists](https://github.com/datacarpentry/r-socialsci/discussions/411)
- [datacarpentry/r-raster-vector-geospatial---Introduction to Geospatial Raster and Vector Data with R](https://github.com/datacarpentry/r-raster-vector-geospatial/issues/369)
- [carpentries/instructor-training---Instructor Training](https://github.com/carpentries/instructor-training/issues/1396)
- [datacarpentry/python-ecology-lesson-es---Análisis y visualización de datos usando Python](https://github.com/datacarpentry/python-ecology-lesson-es/issues/79)
- [datacarpentry/OpenRefine-ecology-lesson---Data Cleaning with OpenRefine for Ecologists](https://github.com/datacarpentry/OpenRefine-ecology-lesson/discussions/275)
- [datacarpentry/R-ecology-lesson---Data Analysis and Visualization in R for Ecologists](https://github.com/datacarpentry/R-ecology-lesson/discussions/799)
- [librarycarpentry/lc-shell---Library Carpentry: The UNIX Shell](https://github.com/LibraryCarpentry/lc-shell/discussions/211)
### Community Lessons
The following community lessons will be migrated to the Workbench during the
beta phase. At the moment, there is no definite timeline, but we will update
that soon. Note that these lessons will skip directly from pre-beta into
pre-release.
- [carpentries-incubator/git-novice-branch-pr---Version Control with Git](https://github.com/carpentries-incubator/git-novice-branch-pr)
- [carpentries-incubator/data-management-pipelines-engineering---Data management and analytic pipelines for engineers](https://github.com/carpentries-incubator/data-management-pipelines-engineering)
- [carpentries-incubator/markdown-intro---Introduction to Markdown](https://github.com/carpentries-incubator/markdown-intro)
- [carpentries-incubator/SDC-BIDS-IntroMRI---Introduction to MRI and BIDS](https://github.com/carpentries-incubator/SDC-BIDS-IntroMRI)
- [carpentries-incubator/SDC-BIDS-dMRI---Introduction to dMRI](https://github.com/carpentries-incubator/SDC-BIDS-dMRI)
- [carpentries-incubator/SDC-BIDS-fMRI---fMRI Imaging Analysis](https://github.com/carpentries-incubator/SDC-BIDS-fMRI)
- [carpentries-incubator/julia-novice---A lesson exploring the Julia language](https://github.com/carpentries-incubator/julia-novice)
- [carpentries-incubator/R-archaeology-lesson](https://github.com/carpentries-incubator/R-archaeology-lesson/issues/4#issuecomment-1138641684)
- [carpentries-incubator/python-packaging-publishing---Packaging and Publishing with Python](https://github.com/carpentries-incubator/python-packaging-publishing)