-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathtcw22.xml
More file actions
664 lines (624 loc) · 46.9 KB
/
tcw22.xml
File metadata and controls
664 lines (624 loc) · 46.9 KB
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
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
<?xml version="1.0" encoding="UTF-8"?>
<TEI xmlns="http://www.tei-c.org/ns/1.0">
<teiHeader>
<fileDesc>
<titleStmt>
<title>TCW22: Building a TEI Release</title>
<author xml:id="MDH">Martin Holmes</author>
<author>James Cummings</author>
<author>Lou Burnard</author>
<author>Sebastian Rahtz</author>
<author>David Sewell</author>
<author xml:id="KSH">Kevin Hawkins</author>
<author xml:id="HC">Hugh Cayless</author>
<author xml:id="PS">Peter Stadler</author>
<author xml:id="EM">Elli Mylonas</author>
<editor xml:id="EBB">Elisa Beshero-Bondar</editor>
<author xml:id="RV">Raffaele Viglianti</author>
<author xml:id="JL">Jessica H. Lu</author>
<!-- Note: I mean <editor> as per Guidelines: secondary
intellectual responsibility, rather than as an actual
editor. —Syd, 2021-04-16 -->
<editor xml:id="SDB">Syd Bauman</editor>
<editor xml:id="POC">Patricia O Connor</editor>
</titleStmt>
<publicationStmt>
<publisher>TEI Technical Council</publisher>
<date>2018</date>
</publicationStmt>
<sourceDesc>
<p>This document was originally a section of tcw20.xml, but has now been spun off into its
own document.</p>
</sourceDesc>
</fileDesc>
<revisionDesc>
<change when="2026-02-18" who="#POC">Add missing links and correct incorrect links in the
release instructions</change>
<change when="2025-09-06" who="#EBB">Added guidance to check links in release notes, including
links to latest corrected version of past release notes.</change>
<change when="2025-08-27" who="#SDB">Per HBS, move “merge into "released"” steps up to
immediately after the push into the "release-X.X.X" step.</change>
<change when="2025-03-31" who="#POC">Revised and updated procedure as some checking steps are
currently listed after the released branch is created. Moved steps 6 and 7 to after step
14.</change>
<change when="2025-01-22" who="#RV">Removed any mentions of Jenkins 3, now defunct.</change>
<change when="2024-11-02" who="#EBB">Clarified where to check on the Vault for the current
releases of Stylesheets and Guidelines needed for building the oXygen plugin. Revised
instructions on how to update the table of releases for the GitHub website.</change>
<change when="2024-07-17" who="#POC">Added reminder to review release-blocker labelled
issues.</change>
<change when="2024-06-21" who="#RV">Added reminder to mention in the Release Notes any changes
affecting ODD customizations.</change>
<change when="2023-11-16" who="#RV">Updated Docker build info to account for new Roma (was
Romabeta) and Roma Antiqua (was Roma). Clarified Stylesheets GitHub release
process.</change>
<change when="2021-04-11" who="#SDB">Per Nick Cole, since $PATH is not set up on server, need
to specify current directory in path to some executables.</change>
<change when="2021-03-12" who="#MDH">Adding a step to update the version of p5subset.xml which
is in the Stylesheets repo, prior to doing any of the release steps.</change>
<change when="2020-02-13" who="#JL">Additional changes based on February 2020 release to make
links visible, clarify release steps, confirm primacy of Paderborn Jenkins server.</change>
<change when="2020-02-13" who="#JL">Update all references, and add links, to Jenkins servers.
Revise instructions regarding release version numbers.</change>
<change when="2020-02-10" who="#EBB">Update all references about ssh to the tei server to the
new HumaNum server consistently. Correct small grammatical errors.</change>
<change when="2019-02-04" who="#EM">Add updates and clarifications learned from last
release.</change>
<change when="2019-01-30" who="#PS">Add information about setting JAVA_HOME for updating the
Debian packages</change>
<change when="2019-01-29" who="#sb">Be explicit about contacting Jenkins maintainers ahead of
time</change>
<change when="2016-09-25" who="mt">Recommendations for issue handling that facilitate
preparing the Release Notes.</change>
<change when="2016-04-02" who="#MDH">Beginning edits arising out of the experiences releasing
3.0.0. More to come.</change>
<change when="2016-03-16" who="#KSH">Fixed error in git command as just reported on
tei-council</change>
<change when="2016-02-23" who="#HC">Edits for new release process.</change>
<change when="2015-12-14" who="#MDH">Updates for new Jenkins server subdomains.</change>
<change when="2015-10-07" who="#MDH">Update for use of ant build process for oxygen-tei rather
than the old .sh file.</change>
<change when="2015-10-04" who="#MDH">More updates to account for the shift from SF SVN to
GitHub.</change>
<change when="2015-10-03" who="#MDH">Updates to account for the shift from SF SVN to
GitHub.</change>
<change when="2015-04-06" who="#MDH">Updates arising out of release process for
2.8.0.</change>
<change when="2015-04-06" who="#KSH">Added link to
http://wiki.tei-c.org/index.php/IRC</change>
<change when="2015-04-04" who="#MDH">Updates to take account of oxygen-tei's move from Google
Code to GitHub, along with a couple of other tweaks.</change>
<change when="2014-01" who="#MDH">Updates for changes in procedure ahead of the 2.6.0
release.</change>
<change when="2013-11" who="#MDH">Updates following move of some code from SourceForge to
GitHub, and automation of the P5 version number in output.</change>
<change when="2012-10-25" who="#MDH">Updates following Primrose Path release
experience.</change>
<change when="2012-07-24" who="#KSH">Newsfeed blog is no longer in SourceForge.</change>
<change when="2012-06-28" who="#KSH">A few changes based on messages to tei-council on
2012-06-19 and 2012-06-20.</change>
<change when="2012-06-19" who="#KSH">Improvements suggested by various Council members based
on experiences with version 2.1.0.</change>
<change when="2012-06-16" who="#KSH">Explained version numbers and added reminder about
including readme file in announcement.</change>
<change when="2012-02-02" who="#MDH">Document forked from tcw20.xml.</change>
<change when="2025-01-24" who="#POC">Added note on needing to update tests after the p5subset
is built and copied into Stylesheets/source.</change>
</revisionDesc>
</teiHeader>
<text>
<body>
<head>Building a TEI Release</head>
<p>This document aims to provide a set of detailed instructions enabling a "release
technician" (the Council member tasked with implementing a new release of the TEI) to
prepare for and manage the release process. The release process normally involves more than
one release technician. In the event that there is more than one release technician, the
release technicians should coordinate and divide the various steps in the release process
amongst themselves.</p>
<div xml:id="issueHandlingGuidelines">
<head>Issue Handling Recommendations</head>
<p>In the lead up to the release, all Council members should review assigned tickets and
adhere to the following general guidance:</p>
<list type="unordered">
<item>Assign tickets to release milestone</item>
<item>Use ticket reference in any commits addressing or fixing the issue</item>
<item>At least for the final commit addressing the issue try to prepare the commit message
so it can be used for Release Notes</item>
<item>Label the issue as Release Note (green label) if it’s important to include the note
about it in Release Notes</item>
</list>
</div>
<div xml:id="githubPackages">
<head>Packages on GitHub</head>
<p>The release process detailed below assumes that the new packages will be taken from one
of the Jenkins servers rather than being built locally by the release technician(s). This
is easier and more reliable, because we ensure that the Jenkins servers are regularly
updated and are correctly configured to build the TEI products.</p>
<p>The TEI maintains a number of distinct repositories on GitHub under the <ref
target="https://github.com/TEIC">TEIC</ref> organization. The main repository for
developing the P5 Guidelines and associated schemas is <ref
target="https://github.com/TEIC/TEI">TEIC/TEI</ref>, and the TEI Stylesheets, the code
for the Roma web application, and the source code for the Oxygen TEI plugin can be found
in <ref target="https://github.com/TEIC/Stylesheets">TEIC/Stylesheets</ref>, <ref
target="https://github.com/TEIC/Roma">TEIC/Roma</ref>, and <ref
target="https://github.com/TEIC/oxygen-tei">TEIC/oxygen-tei</ref> respectively. </p>
<p>The rest of this section describes how to make a new release for the main
<ident>P5</ident> package, but similar procedures apply to the others. The instructions
assume you are working on a Linux or MacOSX system with a command line, and know (more or
less) how to do basic command-line operations such as running scripts and logging into a
server with ssh.</p>
</div>
<div xml:id="beforeStarting">
<head>What you will need before you start</head>
<p><hi rend="bold">Important: Make sure to go through each of the following steps carefully
and well in advance, to avoid delays on Release Day.</hi></p>
<list type="bulleted">
<item>An account on GitHub, and committer privileges over the TEI repository. If you have
ever pushed a change to the TEI repository, you should have all the required
permissions.</item>
<item>Shell access on the TEI SourceForge project. Contact one of the admins to have this
turned on. Normal committers don't have shell access.</item>
<item>The release manager will need SSH login access to the tei account on the tei-c.org
server. This involves two steps: <list type="ordered">
<item>Generate an SSH key pair (if you don't have one already). If this is new to you,
look at <ref target="https://en.wikipedia.org/wiki/Ssh-keygen"
>https://en.wikipedia.org/wiki/Ssh-keygen</ref>.</item>
<item>Send the public key to the Council Chair, who will forward it on to the system
administrator.</item>
</list> Make sure you get this set up well in advance of the release day, and make sure
you can <code>ssh [email protected]</code> successfully. See next steps.
(Note: if you are a member of the Infrastructure Group, you will already have your own
login to the server, but you should test it.)</item>
<item>A copy of the public key that will enable you to sync the release zip with
SourceForge. <list type="ordered">
<item>Log in to the tei server at <code>ssh [email protected]</code>
(this requires that you have already generated the SSH public key and sent it to the
system administrator as outlined in the step above). (Note that if you are a member
of the Infrastructure Group with your own login, log in as yourself, but <code>sudo
su tei</code> before running any scripts.)</item>
<item>Once logged into the tei server complete the following steps: <list>
<item><code>cat ~/.ssh/id_rsa.pub</code> and copy the contents to the
clipboard.</item>
<item>Paste the result into a text editor and remove any linebreaks added by the
terminal.</item>
<item>Copy-paste the result into <ref
target="https://sourceforge.net/auth/shell_services"
>https://sourceforge.net/auth/shell_services</ref></item>
</list> What this does is to enable you (when logged in as tei to tei-c.org) to
connect to SourceForge (as your SF user) to upload the release files. </item>
<item>Test it by trying to log into SourceForge via ssh from the tei-c.org server:<lb/>
<code>ssh sfuser,[email protected]</code><lb/> where "sfuser" is your
SourceForge user name. You should not see a prompt for a password (because of the
ssh keys you have set up). Instead, you should immediately see <q>Welcome! This is a
restricted Shell Account. You can only copy files to/from here.</q> If you see
this, then everything is set up correctly.</item>
</list>
</item>
<item>Some familiarity with the two TEI Jenkins Continuous Integration Servers. <list
type="ordered">
<item><ref target="https://jenkins.tei-c.org">https://jenkins.tei-c.org</ref></item>
<item><ref target="https://jenkins2.tei-c.org">https://jenkins2.tei-c.org</ref></item>
</list> Take a little time to watch them work, and see how a push to the GitHub
repository causes them to start building TEI packages. There are three specific build
jobs associated with P5, and they run in a fixed sequence. Currently, as of February
2020, the actual build for the release will rely on the first Jenkins server, often
referred to as the "Paderborn Jenkins" (maintained by Peter Stadler in Paderborn,
Germany).</item>
<item>Access to the <ref target="https://tei-c.slack.com">TEI Council Slack</ref> which
will be the communication channel during the release process.</item>
<item>Several hours of time. You won't be busy all the time, but the process from
beginning to end takes several hours, especially if something goes a bit wrong and you
have to retrace your steps. It's best to start first thing in the morning, and prepare
to be busy all day.</item>
</list>
</div>
<div xml:id="releaseSteps">
<head>Step-by-step instructions</head>
<list type="ordered">
<head>1-2 weeks before release:</head>
<!-- MDH and SB: Adding a new step to update p5subset.xml in the Stylesheets repo. -->
<item><hi rend="bold">Get p5subset.xml</hi> from a fresh build of the P5 dev branch
(preferably on Jenkins, at a URL such as <ref
target="https://jenkins.tei-c.org/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/xml/tei/odd/p5subset.xml"
>https://jenkins.tei-c.org/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/xml/tei/odd/p5subset.xml</ref>)
and update the version of p5subset.xml in the Stylesheets/source directory in the
Stylesheets dev branch.</item>
<item>Inform the Jenkins maintainers (who may not be on the Council listserv), and the TEI
sysadmin, of the pending release date, so that they can be available or on-call. </item>
<item>Ask one of the Jenkins maintainers (Martin Holmes, Peter Stadler, and Raffaele
Viglianti) to run a link check on the Guidelines and fix broken links in the dev branch. </item>
<item>Ask for the TEI-C GPG key passphrase. You'll need it for signing the Debian
packages. (The GPG private key itself is hosted on the server at the default
location.)</item>
<!-- Revisit the above item, which was called into question during February 2020 release.
If Debian package update is not the responsibility of release technician(s),
and is actually handled by Peter Stadler, this step is not necessary. (JL, 2020-02-13) -->
<item><hi rend="bold">Communicate with the TEI Council chair to make sure that the
P5/ReleaseNotes/readme-X.X.X.xml is compiled</hi><lb/> Normally, this will be created
by the TEI Council chair at the point when the repository moved from its "alpha" stage
to "beta", following these steps: <list type="bulleted">
<item>Confirm the version number for the new release in consultation with Council. TEI
version numbers are based on the Unicode Consortium system (<ref
target="http://www.unicode.org/versions/">http://www.unicode.org/versions/</ref>)
but with the first digit for major changes, the second for schema-changing
revisions, and the third for non-schema-changing revisions. When the first or second
digit is incremented, the following digit or digits is set to zero. During initial
development, the version number is followed by "alpha"; during the pre-release
checking stage, it's followed by "beta"; and when the release takes place, "beta" is
removed and the version number has only digits and periods.</item>
<item>Create the new file by cloning a previous one.</item>
<item>Consult the git log to check for all the significant changes since the last
release. You can do this by opening a terminal in the root of a working copy of the
TEI repository and running:<lb/>
<code>git log --after=2015-08-01</code><lb/> where the date is that of the previous
release. </item>
<item>The Release Notes ought to list changes that affect ODD customizations even when
they do not affect the resulting schemata, such as (but not limited to) the renaming
of a class, or the moving of an attribute definition from an element to an attribute
class.</item>
<item>Add the new file into the repository with <code>git add
P5/ReleaseNotes/readme-X.X.X.xml</code>. Be sure to change X.X.X with the version
numbers.</item>
</list>
</item>
<item><hi rend="bold">Review all issues labelled as Release Blocker (red
label)</hi><lb/><!-- Adding this reminder in bold, as requested following the July 2024 release to ensure that all tickets labelled as release blockers are reviewed and fixed prior to the release. -->
At least one week before releasing, we enter a review period, during which the only
changes made to the code to be released should be to fix errors, rather than to add new
features. Release branches for the TEI and Stylesheets repos will be created by the
release technician(s), to which ONLY release-blocking bug fixes and corrections to
typographical errors will be pushed. The release technician(s) should announce a
temporary hold on pushes to the dev branches on the Council list, then create the
release branches and push it to GitHub using the following commands, once in the TEI
repo and once in the Stylesheets repo: <lb/><code>git checkout dev</code> (make sure you
start from the dev branch) or if you have the dev branch checked out, <code>git
status</code> in order to make sure that you have the current version and no
uncommitted changes. <lb/><code>git checkout -b release-X.X.X</code>
<lb/><code>git push -u origin release-X.X.X</code></item>
<item>Immediately after the release branches have been pushed, the release technician(s)
should inform the <ref target="mailto:[email protected]">Council list</ref>
and ask the maintainers of the TEI Jenkins systems to add a build of the release branch
so that commits pushed there are properly tested, and advise them of the release
schedule. Remember that the maintainers (currently Martin Holmes, Peter Stadler, and
Raffaele Viglianti) may not be on the Council list. Verify with the maintainers that
both Jenkins servers are functioning properly.</item>
<item>Pushes to the release branch should be merged back into dev regularly:
<lb/><code>git checkout dev</code>
<lb/><code>git merge release-X.X.X</code></item>
</list>
<list type="ordered">
<head>On release day:</head>
<item>The instructions below for Git commands are assumed to be run in the release-X.X.X
branches unless otherwise specified. If there is more than one release technician, one
of the release technicians should create the release branch and the other release
technicians can set up a copy of the release branch using the following commands:<lb/>
<code>git pull origin</code> (to make sure your copy knows about the release branch)<lb/>
<code>git checkout --track origin/release-X.X.X</code>
</item>
<item>Check the release notes for typos, link issues, or other glaring errors, one last
time. If the current release notes mention revision of past release notes, check that
the link URL is pointing to the current release in the Vault, which will contain the
full collection of release notes. For example, for a revision to release notes in 4.10.0
in release 4.10.2, the URL should be: <ref
target="https://www.tei-c.org/Vault/P5/4.10.2/doc/tei-p5-doc/readme-4.10.0.html"
>https://www.tei-c.org/Vault/P5/<hi rend="bold">4.10.2</hi>/doc/tei-p5-doc/<hi
rend="bold">readme-4.10.0.html</hi></ref>. </item>
<item><hi rend="bold">Edit the P5/VERSION file to the correct number</hi><lb/> Change
directory to TEI/P5 <code>cd TEI/P5</code>.<lb/> To open the VERSION file, enter
<code>nano VERSION</code>.<lb/> This file consists only of the bare version number,
followed by "alpha" or "beta":<lb/>
<code>2.8.2b</code><lb/> For the release process, you need to remove the letters from
the end, leaving a pure version number:<lb/>
<code>2.8.2</code><lb/> This changes the release from beta (or possibly alpha) to the
actual release version number.<lb/> Save your changes to the VERSION file using the
keyboard keys <code>Ctrl + S</code>.<lb/> Exit the file using the keyboard keys
<code>Ctrl + X</code>.<lb/> Commit your changes with the command <code>git commit -a
-m "Update VERSION number"</code>.<lb/> Push your changes with the command <code>git
push</code>.<lb/>
</item>
<!-- MDH and SB: Adding a new step to update p5subset.xml in the Stylesheets repo. -->
<item><hi rend="bold">Get p5subset.xml</hi> from a fresh build of the P5 release branch
(preferably on Jenkins, at a URL such as
https://jenkins.tei-c.org/job/TEIP5-release-X.X.X/lastSuccessfulBuild/artifact/P5/release/xml/tei/odd/p5subset.xml)
and update the version of p5subset.xml in the Stylesheets/source directory in the
Stylesheets release-X.X.X branch. <lb/>
<hi rend="bold">Note:</hi> Tests may need to be updated after copying the updated
p5subset.xml file to the Stylesheets/source directory of the Stylesheets release-X.X.X
branch. It is recommended to use <code>make DIFFNOW=0 test</code> as this will generate
all the actual results and then compare against the expected results afterwards. Once
the actual results are generated, you have to manually compare the expected-results and
actual-results folders (both under Stylesheets\Test\) and check through all of the files
containing differences.</item>
<item><hi rend="bold">Announce a freeze on pushes to the release branch on the TEI
Technical Council mailing list</hi></item>
<item><hi rend="bold">Commit your changes to the P5 release branch
<code>release-X.X.X</code></hi>. <lb/>
</item>
<item><hi rend="bold">Complete the following steps for the Stylesheets</hi> (have a
stylesheets expert on hand to help debug problems):<lb/>
<list type="ordered">
<item>Edit the Stylesheets/VERSION number to the correct release number (usually just
remove the 'a'). <lb/> To update the VERSION file, first change directory to the
Stylesheets. If you are already in the TEI/P5 directory you could change directory
to the Stylesheets using the following command: <code>cd
../../Stylesheets</code><lb/> To open the VERSION file, enter <code>nano
VERSION</code>.<lb/> Remove the letter at the end and save your changes using the
keyboard keys <code>Ctrl + S</code>.<lb/> Exit the file using the keyboard keys
<code>Ctrl + X</code><lb/>. Commit your changes with the command <code>git commit
-a -m "Update VERSION number"</code>.<lb/> Push your changes with the command
<code>git push</code><lb/>.</item>
<item>Run <code>make log</code> to generate the changelog. Then commit the
changes.</item>
<item>Merge the release branch into the <code>dev</code> branch<lb/>
<code>git checkout dev</code><lb/>
<code>git merge release-X.X.X</code>
</item>
<item>Merge the release branch into <code>released</code><lb/>
<code>git checkout released</code><lb/>
<code>git merge --no-ff -m "YOUR COMMIT MESSAGE" release-X.X.X</code>
</item>
</list>
</item>
<!-- Steps 5 and 6 which instruct on how to merge the release branch into the released branch were originally here, but for the Jan 2025 creating the released branch at this point proved to be too early in the process and have now been moved after step 14 -->
<item><hi rend="bold">Push your changes</hi> for both P5 and the Stylesheets to the git
repository, <code>git push origin release-X.X.X</code><lb/> and watch Jenkins build P5
for you.<lb/> This should be the final push for this version, and it will trigger the
Jenkins servers to rebuild the TEI packages. As a reminder, you can find the Jenkins
servers here: <list type="bulleted">
<item><ref target="https://jenkins.tei-c.org">https://jenkins.tei-c.org</ref></item>
<item><ref target="https://jenkins2.tei-c.org">https://jenkins2.tei-c.org</ref></item>
</list> And now you wait while the Jenkins servers build the packages, keeping in mind
that subsequent steps will require the build packages from the Paderborn Jenkins server
(as of February 2020). This can take a couple of hours, so be patient. <!-- As of February 2020, the following sentence, which previously appeared in the TCW,
was proven false.
"All of the Jenkins servers should behave
identically, and they should all build all three TEI packages successfully." (RV, EB, JL, 2020-02-13) -->
<hi rend="bold">Note</hi>: The P5 and Stylesheets builds have reciprocal dependencies,
so the first build of either the Stylesheets or the Guidelines may fail just because
there isn't yet a current build of the other for it to use. This isn't a cause for
panic, but it may mean that (e.g.) the Stylesheets build needs to run twice. In
particular, the Stylesheets build may fail after the TEI release is complete, so it is
better to wait until the TEI release is complete before doing the Stylesheets release.
(Council is considering changing how the dependency is managed).</item>
<item>
<hi rend="bold">Merge the release branch into the <code>dev</code> and
<code>released</code> branches</hi>. <list type="ordered">
<item><code>git checkout released</code></item>
<item><code>git merge --no-ff -m "YOUR COMMIT MESSAGE" release-X.X.X</code></item>
<item><code>git checkout dev</code></item>
<item><code>git merge --no-ff -m "YOUR COMMIT MESSAGE" release-X.X.X</code></item>
<item>Don’t forget to switch to the released branch <code>git checkout
released</code></item>
</list>
</item>
<item>
<hi rend="bold">Repeat the steps above for the Stylesheets</hi>. <list type="ordered">
<item><code>git checkout released</code></item>
<item><code>git merge --no-ff -m "YOUR COMMIT MESSAGE" release-X.X.X</code></item>
<item><code>git checkout dev</code></item>
<item><code>git merge --no-ff -m "YOUR COMMIT MESSAGE" release-X.X.X</code></item>
<item>Don't forget to switch back to the released branch <code>git checkout
released</code></item>
</list>
</item>
<item><hi rend="bold">Ensure all changes have been committed, built, and successfully
passed tests on the continuous integration server</hi><lb/> When all builds have
completed on all Jenkins servers, click on the job number of the last build for each of
the three TEI jobs to make sure that it was triggered by the commit that you made in the
previous step (you should see your own commit message on the build page). Make sure that
all builds were successful (they should have green balls next to them). In the case of
red balls, indicating a failed build, seek support via the TEI Council Slack. </item>
<item>
<hi rend="bold">Log into TEI server and run the tei-install.sh script:</hi><lb/> Log
into the TEI server via <code>ssh [email protected]</code>. Note that if
you are a member of the Infrastructure Group with your own login, log in as yourself,
but <code>sudo su tei</code> before running any commands. Then fetch the current version
of the install script by issuing <code>curl
https://raw.githubusercontent.com/TEIC/TEI/dev/P5/Utilities/tei-install.sh -o
~/tei-install.sh</code>. <lb/> (If you'll need to tweak that script later during the
install process please make sure to feed the changes back to the original script in the
TEI repo.) <lb/>In each of the following steps, <emph>replace the Xs with your release
version number</emph>. Supply your SourceForge user name, and type your SourceForge
password when prompted. By default, the script will pull the release package from the
first Jenkins server, but you can supply the URL of the other server if necessary with
the --Jenkins parameter, e.g. <code>--Jenkins=http://jenkins2.tei-c.org/</code>. Make
sure the script completes successfully each time changing the final parameter from
<code>--install</code>, to <code>--makecurrent</code>, and then <code>--upload</code>.
<lb/>Following the above guidance, complete these three steps: <list type="bulleted">
<item>Install on tei-c.org: <code>./tei-install.sh --package=TEIP5 --version=X.X.X
--sfuser=username --install</code> and then <emph>go test the version this puts in
the <ref target="https://www.tei-c.org/Vault/P5/">Vault</ref></emph>.</item>
<item>If that looks good and everyone agrees then: <code>./tei-install.sh
--package=TEIP5 --version=X.X.X --sfuser=username --makecurrent</code> and then
<emph>test that it appears on website correctly</emph>.</item>
<item>If the website looks right then: <code>./tei-install.sh --package=TEIP5
--version=X.X.X --sfuser=username --upload</code> and then move on to the next
step.</item>
</list>
</item>
<item><hi rend="bold">Repeat the steps above for the Stylesheets</hi>, remembering that
the version number is the Stylesheets version, which will be different from the
Guidelines version: <lb/><list type="bulleted"><item><code>./tei-install.sh --package=Stylesheets --version=X.X.X
--sfuser=username --install</code> and then <emph>go test the version this puts in
the <ref target="https://www.tei-c.org/Vault/stylesheets/">Vault</ref></emph>.</item>
<lb/><item>If that looks good and everyone agrees then:<code>./tei-install.sh --package=Stylesheets --version=X.X.X --sfuser=username
--makecurrent</code> and then
<emph>test that it appears on website correctly</emph>.</item>
<lb/><item>If the website looks right then: <code>./tei-install.sh --package=Stylesheets --version=X.X.X --sfuser=username
--upload</code></item>
<lb/></list>
</item>
<item><hi rend="bold">Check the TEI website and all downloadable files are displaying the
correct version</hi><lb/> Everything should now be done, so go to <ref
target="https://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html">the newly
released version on the TEI site</ref> and browse the Guidelines. Check that your
version number is displayed in the footer of the page, and check that at least one
change made since the last release is being reflected online. </item>
<item><hi rend="bold">Update <ref target="https://roma.tei-c.org/">Roma</ref>, <ref
target="https://romaantiqua.tei-c.org/">Roma Antiqua</ref>, and <ref
target="https://teigarage.tei-c.org/">TEIGarage</ref></hi>
<lb/>Change to the directory <code>~/repos/infrastructure/humanum</code>, do a <code>git
pull</code>, and issue the script <code>docker-update.sh</code> for every service,
i.e. <list>
<item><code># ./docker-update.sh roma</code></item>
<item><code># ./docker-update.sh romaantiqua</code></item>
<item><code># ./docker-update.sh oxgarage</code></item>
<item><code># ./docker-update.sh teigarage</code></item>
</list> NB: Every invocation might take some time but each should successfully finish
with the notification "Creating $CONTAINER$ ... done" </item>
<item>
<hi rend="bold">Make your release the default downloadable version from
Sourceforge</hi><lb/> Go to the SourceForge site (<ref
target="https://sourceforge.net/projects/tei/files/TEI-P5-all/"
>https://sourceforge.net/projects/tei/files/TEI-P5-all/</ref>), log in, and click the
information button on your new release. Make it the default download for all operating
systems. Now make sure that the main Download button links to your package. </item>
<item>
<hi rend="bold">Update tags on GitHub</hi><lb/> Every time a new release is made, a
"tag" is created consisting of a pointer to the state of the P5 tree at release time.
You can do this from the command line on your own computer. Before moving forward, be
sure to do a <code>git pull</code> and update your <code>released</code> branch.<lb/>
<code>git checkout released</code><lb/>
<code>git pull</code><lb/> Then, still in the released branch, do:<lb/>
<code>git tag -a P5_Release_X.X.X -m "Release X.X.X of the TEI Guidelines."</code><lb/>
where X.X.X is your new release. Then<lb/>
<code>git push origin P5_Release_X.X.X</code><lb/> Do the same for the Stylesheets as
well, on the released branch:<lb/>
<code>git checkout released</code><lb/>
<code>git pull</code><lb/>
<code>git tag -a vX.X.X -m "Release X.X.X of the TEI Stylesheets."</code><lb/> where
X.X.X is your new release. Then<lb/>
<code>git push origin vX.X.X</code>
</item>
<item><hi rend="bold">Make a Release on GitHub</hi><lb/> Go to the TEI Tags page at <ref
target="https://github.com/TEIC/TEI/tags">https://github.com/TEIC/TEI/tags</ref> on
GitHub. You should see the tag you just pushed there. Click on it and then click on
"Create Release". Add a link to the release notes README, which should be at
https://www.tei-c.org/release/doc/tei-p5-doc/readme-X.X.X.html, into the text box. Add a
copy of the zipped release by downloading it from <ref
target="https://jenkins.tei-c.org/job/TEIP5/lastSuccessfulBuild/artifact/P5/"
>https://jenkins.tei-c.org/job/TEIP5/lastSuccessfulBuild/artifact/P5/</ref> and then
uploading it to the release page.<lb/> Do the same for the Stylesheets as well. Go to
the Stylesheets Tags page at <ref target="https://github.com/TEIC/Stylesheets/tags"
>https://github.com/TEIC/Stylesheets/tags</ref> on GitHub and follow the same
procedure. Be sure to add a copy of the zipped release by downloading it from <ref
target="https://jenkins.tei-c.org/job/Stylesheets/lastSuccessfulBuild/artifact/"
>https://jenkins.tei-c.org/job/Stylesheets/lastSuccessfulBuild/artifact/</ref> and then
uploading it to the release page. </item>
<item><hi rend="bold">Close/Add GitHub Milestones</hi><lb/> Go to the Milestones page of
both the <ref target="https://github.com/TEIC/Stylesheets/milestones">Stylesheets</ref>
and the <ref target="https://github.com/TEIC/TEI/milestones">Guidelines</ref> repo. Add
new Milestones by incrementing the minor version number part and move all open issues
from the current Milestone to the new one. (If Council already decided on the next
release date (unlikely) you can add the date to the new Milestone. Otherwise leave
empty.) Finally, close the current Milestone (do not delete it).</item>
<item><hi rend="bold">Update the Debian Package repository with the new release</hi><lb/>
The TEI Debian packages are regularly created during each Jenkins build. For each
release you need to update the TEI Debian repository at <ref
target="http://packages.tei-c.org/deb/">http://packages.tei-c.org/deb/</ref> which can
be done by simply running <code>ant</code> on the TEI server within the
<code>/data/debian-packages</code> directory. (This directory is cloned from <ref
target="https://github.com/TEIC/TEI-apt-repo"
>https://github.com/TEIC/TEI-apt-repo</ref>) <emph>Since the repository index needs to
be signed, you'll need the passphrase for the GPG key.</emph> Make sure you've
received it in advance! <lb/>Once the process has finished and the repo is updated, the
page at <ref target="http://packages.tei-c.org/deb/"
>http://packages.tei-c.org/deb/</ref> should reflect the changes immediately. If not,
try to restart the NGINX Docker container that serves this directory with <code>docker
restart debian-packages</code>.
<!--<lb/>Another caveat: <code>ant</code> fails to fetch the packages via HTTPS when
running an outdated Java VM. Make sure to set the environment variable <code>JAVA_HOME</code>
to some appropriate version! At present <code>export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64</code>
will do.-->
</item>
<item>
<hi rend="bold">Update the table of previous releases of P5 in the GitHub repo for the
TEI-C website</hi>. The table is found in the <code>src/guidelines/p5.md</code> file
in the <ref target="https://github.com/TEIC/website">website</ref> repository; it is
published at <ref target="https://tei-c.org/guidelines/p5/#releases"
>https://tei-c.org/guidelines/p5</ref>. <lb/>Add the new release information and links
to the top of the release table.</item>
<item><hi rend="bold">Update the oXygen-ready distribution of TEI.</hi><lb/> This involves
building the new package of oxygen-tei, and then updating the distribution file on the
TEI server so that the oXygen software knows about the new release. You may request to
hand this off to one of the maintainers (currently Syd Bauman, James Cummings, or Martin
Holmes) to do this for you if you're not familiar with the project. <list
type="bulleted">
<item>Check that you have ant (at least version 1.8) installed on your machine.</item>
<!-- MDH 2021-04-19: Added release="8" to javac call in framework/build.xml, and this now seems to
build fine with Java 14. Commenting out this step. -->
<!--<item>Check that your current Java version is 1.8. This is an old version, but it is currently
required for building the oxygen-tei package. If you are on e.g. Ubuntu Linux, you can
install multiple Java versions and switch between them easily using <code>sudo update-alternatives -\-config java</code>. </item>-->
<item>Check that the latest versions of the Stylesheets and TEI P5 are available from
the TEI Vault, since the oxygen-tei update/upload script retrieves them from there.
<list type="unordered">
<item>Check for the Stylesheets at <ref
target="https://tei-c.org/Vault/Stylesheets/"
>https://tei-c.org/Vault/Stylesheets/</ref>.</item>
<item>Check for the Guidelines at <ref target="https://tei-c.org/Vault/P5/"
>https://tei-c.org/Vault/P5/</ref>.</item>
</list>
</item>
<item>Check out or update a local copy of the source code from <ref
target="https://github.com/TEIC/oxygen-tei"
>https://github.com/TEIC/oxygen-tei</ref> to your local system.</item>
<item>Change directory to the oxygen-tei folder<lb/>
<code>cd oxygen-tei</code><lb/> List the contents of the folder to double check by
entering <code>ls</code>. The folder should contain folders called "frameworks" and
"jenkins".</item>
<item>Run the ant build process with the "release" parameter: <lb/>
<code>ant release</code><lb/> This builds the plugin using the latest stable
versions of P5 and the Stylesheets, then offers to upload the result to the TEI's
SourceForge repo to become a release of the TEI-maintained version of the plugin.
This also creates an updated updateSite.oxygen file, by retrieving the latest
updateSite.oxygen file from the tei-c.org site, and asks the user to provide the new
version number before creating a new version of updateSite.oxygen. </item>
<item>Go to the <ref target="https://github.com/TEIC/oxygen-tei/releases"
>TEIC/oxygen-tei</ref> GitHub repo and create a new release, using the <code>Draft
new release</code> button. Copy the previous release info (tag, title, and text),
and tweak the versions as appropriate. The tag should be <code>vx.x.x</code> (don’t
forget the <emph>v</emph>!), the title will be <code>Release x.x.x</code>, and the
text <quote>Release number X of the oXygen TEI plugin, based on TEI P5 x.x.x and
Stylesheets x.x.x.</quote></item>
<item>Attach the zip file you just created in the build process, which will be named
something like <code>oxygen-tei-x.x.x-x.x.x.zip</code>, with the numbers from the
current TEI and Stylesheets releases.</item>
<item>Once the tag/release has been published, run <lb/><code>ant
uploadOxygenUpdateFile</code><lb/> to push the <code>updateSite.oxygen</code> file
up to the TEI server.</item>
</list>
</item>
<item><hi rend="bold">Inform the TEI Technical Council Chair so they can announce the
release</hi><lb/> Once you are sure that everything is working correctly, inform the
Council Chair. They will announce the release to the TEI-L mailing list, including the
text of P5/ReleaseNotes/readme-X.X.X.xml in plain text form (which can be generated
using the "readme" profile for teitotxt), and place an announcement on the Text Encoding
Initiative Newsfeed blog in the category of '<ref target="https://tei-c.org/news/"
>News</ref>'. The Chair should contact the Social Media coordinator (currently Anna
Sofia Lippolis) to help spread the news.</item>
<item><hi rend="bold">Lift the freeze on committing changes to the repository</hi><lb/>
Write to the TEI Council list and let them know that they can once again start
committing changes to the repository.</item>
<item><hi rend="bold">Increment the build number for the next release cycle</hi><lb/>
Recalling how release preparation requires confirmation of version number, use your best
judgment to determine the version number for the next release (in consultation with
Council, if possible). TEI version numbers are based on the Unicode Consortium system
(<ref target="http://www.unicode.org/versions/"
>http://www.unicode.org/versions/</ref>) but with the first digit for major changes, the
second for schema-changing revisions, and the third for non-schema-changing revisions.
When the first or second digit is incremented, the following digit or digits is set to
zero. <!-- Revisit version control instructions at May 2020 F2F (JL, 2020-02-13) -->
After the release process has been completed, the release number for both P5 and the
Stylesheets needs to be updated. On the dev branch, edit the P5/VERSION file and the
Stylesheets/VERSION file to the correct numbers. These files contain nothing except the
bare version number. It should be incremented appropriately, and "a" added to the end of
it, so if for example the release was number 2.8.0, you would change the number in the
file to:<lb/>
<code>2.9.0a</code><lb/> signifying that the versions built subsequent to the release
are now in the alpha stage. </item>
</list>
</div>
</body>
</text>
</TEI>