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. It assumes that the new packages will be taken
- from one of the Jenkins servers rather than being built locally by the release technician.
- 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.
+ 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.
+
+
Packages on GitHub
-
The TEI maintains a number of distinct repositories on GitHub under the
- [TEIC](https://github.com/TEIC) organization. The main repository for developing the P5 Guidelines
- and associated schemas is [TEIC/TEI](https://github.com/TEIC/TEI), and the TEI Stylesheets, the code for
- the Roma web application, and the source code for the Oxygen TEI plugin can be found in
- [TEIC/Stylesheets](https://github.com/TEIC/Stylesheets),
- [TEIC/Roma](https://github.com/TEIC/Roma), and
- [TEIC/oxygen-tei](https://github.com/TEIC/oxygen-tei) respectively.
+
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.
+
The TEI maintains a number of distinct repositories on GitHub under the [TEIC](https://github.com/TEIC) organization. The main repository for
+ developing the P5 Guidelines and associated schemas is [TEIC/TEI](https://github.com/TEIC/TEI), and the TEI Stylesheets, the code
+ for the Roma web application, and the source code for the Oxygen TEI plugin can be found
+ in [TEIC/Stylesheets](https://github.com/TEIC/Stylesheets), [TEIC/Roma](https://github.com/TEIC/Roma), and [TEIC/oxygen-tei](https://github.com/TEIC/oxygen-tei) respectively.
The rest of this section describes how to make a new release for the main
P5 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
@@ -113,75 +152,70 @@
What you will need before you start
+
Important: Make sure to go through each of the following steps carefully
+ and well in advance, to avoid delays on Release Day.
- 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.
+ ever pushed a change to the TEI repository, you should have all the required
+ permissions.
- Shell access on the TEI SourceForge project. Contact one of the admins to have this
turned on. Normal committers don't have shell access.
- - The release manager will need SSH login access to the tei account on the tei-c.org
+
- The release manager will need SSH login access to the tei account on the tei-c.org
server. This involves two steps:
- Generate an SSH key pair (if you don't have one already). If this is new to you,
look at
[https://en.wikipedia.org/wiki/Ssh-keygen](https://en.wikipedia.org/wiki/Ssh-keygen).
-
- Send the public key to the Council Chair, who will forward it on to the system
administrator.
Make sure you get this set up well in advance of the release day, and make sure
- you can ssh tei@cchum-kvm-dockerteic.in2p3.fr successfully. (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.)
-
- - Some familiarity with the two TEI Jenkins Continuous Integration Servers.
-
- [https://jenkins.tei-c.org](https://jenkins.tei-c.org)[https://jenkins2.tei-c.org](https://jenkins2.tei-c.org)
- Take a little time to watch them work, and see how a push to the GitHub
+ you can ssh tei@cchum-kvm-dockerteic.in2p3.fr 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.)
+
+ - A copy of the public key that will enable you to sync the release zip with
+ SourceForge.
+ - Log in to the tei server at
ssh tei@cchum-kvm-dockerteic.in2p3.fr
+ (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 sudo
+ su tei before running any scripts.)
+ - Once logged into the tei server complete the following steps:
+ cat ~/.ssh/id_rsa.pub and copy the contents to the
+ clipboard.- Paste the result into a text editor and remove any linebreaks added by the
+ terminal.
+ - Copy-paste the result into
[https://sourceforge.net/auth/shell_services](https://sourceforge.net/auth/shell_services)
+
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.
+
+ - Test it by trying to log into SourceForge via ssh from the tei-c.org server:
+ ssh sfuser,tei@frs.sourceforge.net
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 Welcome! This is a
+ restricted Shell Account. You can only copy files to/from here.
If you see
+ this, then everything is set up correctly.
+
+
+ - Some familiarity with the two TEI Jenkins Continuous Integration Servers.
+ [https://jenkins.tei-c.org](https://jenkins.tei-c.org)[https://jenkins2.tei-c.org](https://jenkins2.tei-c.org)
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).
- - Access to the
[TEI Council Slack](https://tei-c.slack.com)
- which will be the communication channel during the release process.
+ 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).
+ - Access to the
[TEI Council Slack](https://tei-c.slack.com) which
+ will be the communication channel during the release process.
- 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.
-
- - A copy of the public key that will enable you to sync the release zip with
- SourceForge.
- - log in to the tei server at ssh tei@cchum-kvm-dockerteic.in2p3.fr (this requires that you've completed
- the other public key step above). (Note that if you are a member of the Infrastructure Group
- with your own login, log in as yourself, but sudo su tei before running any scripts.)
- cat ~/.ssh/id_rsa.pub and copy the contents to the clipboard.- paste the result into a text editor and remove any linebreaks added by the
- terminal.
- - copy-paste the result into https://sourceforge.net/auth/shell_services
-
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.
-
- - Test it by trying to log into SourceForge via ssh from the tei-c.org server:
- ssh sfuser,tei@frs.sourceforge.net
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 Welcome! This is a restricted Shell
- Account. You can only copy files to/from here.
If you see this, then everything is
- set up correctly.
-
-
-
-
-
- Issue Handling Recommendations
-
- - Assign tickets to release milestone
- - Use ticket reference in any commits addressing or fixing the issue
- - At least for the final commit addressing the issue try to prepare the commit message so it can be used for Release Notes
- - Label the issue as Release Note (green label) if it’s important to include the note about it in Release Notes
-
-
@@ -190,81 +224,93 @@
1-2 weeks before release:
- Get p5subset.xml from a fresh build of the P5 dev branch (preferably on Jenkins, at a URL such as
- https://jenkins.tei-c.org/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/xml/tei/odd/p5subset.xml) and
- update the version of p5subset.xml in the Stylesheets/source directory in the Stylesheets dev branch.- 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.
- - Ask one of the Jenkins maintainers (Peter Stadler and Martin Holmes)
- to run a link check on the Guidelines and fix broken links in the dev branch.
- - 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.)
-
- Communicate with the TEI Council chair to make sure that the P5/ReleaseNotes/readme-X.X.X.xml
- is compiled
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:
+ Communicate with the TEI Council chair to make sure that the
+ P5/ReleaseNotes/readme-X.X.X.xml is compiled
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:
- Confirm the version number for the new release in consultation with Council. TEI
- version numbers are based on the Unicode Consortium system (
[http://www.unicode.org/versions/](http://www.unicode.org/versions/)) 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.
+ version numbers are based on the Unicode Consortium system ([http://www.unicode.org/versions/](http://www.unicode.org/versions/))
+ 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.
- Create the new file by cloning a previous one.
- - Consult the git log log to check for all the significant changes since the last
+
- 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:
git log --after=2015-08-01
where the date is that of the previous
release.
- - 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.
- - Add the new file into the repository with
git
- add.
+ - 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.
+ - Add the new file into the repository with
git add
+ P5/ReleaseNotes/readme-X.X.X.xml. Be sure to change X.X.X with the version
+ numbers.
Review all issues labelled as Release Blocker (red label)
At least one week before releasing, we enter a review period, during which the only
+ Review all issues labelled as Release Blocker (red
+ label)
+ 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, to which ONLY
- release-blocking bug fixes and corrections to typographical errors will be pushed. The
- release technician should announce a temporary hold on pushes to the dev branches on the
- Council list, then create the branches and push it to GitHub using the following commands, once in the
- TEI repo and once in the Stylesheets repo:
-
git checkout dev (make sure you start from the dev branch) or if you have the dev branch
- checked out, git status in order to make sure that you have the current version and no uncommitted changes.
-
git checkout -b release-X.X.X
-
git push -u origin release-X.X.X- Immediately after the release branches have been pushed,
- the release technician should inform the
[Council
- list](mailto:tei-council@lists.tei-c.org) 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.
+ 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:
git checkout dev (make sure you
+ start from the dev branch) or if you have the dev branch checked out, git
+ status in order to make sure that you have the current version and no
+ uncommitted changes.
git checkout -b release-X.X.X
+
git push -u origin release-X.X.X- Immediately after the release branches have been pushed, the release technician(s)
+ should inform the
[Council list](mailto:tei-council@lists.tei-c.org)
+ 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.
- Pushes to the release branch should be merged back into dev regularly:
-
git checkout dev
-
git merge release-X.X.X
-
+
git checkout dev
+
git merge release-X.X.X
+
On release day:
- The instructions below for Git commands are assumed to be run in the release-X.X.X
- branches unless otherwise specified. If you did not create the release branch, you can
- set up a copy of it using the following commands:
+ 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:
git pull origin (to make sure your copy knows about the release branch)
git checkout --track origin/release-X.X.X
- - 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:
-
[https://www.tei-c.org/Vault/P5/](https://www.tei-c.org/Vault/P5/4.10.2/doc/tei-p5-doc/readme-4.10.0.html)4.10.2/doc/tei-p5-doc/readme-4.10.0.html.
-
+ - 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:
[https://www.tei-c.org/Vault/P5/](https://www.tei-c.org/Vault/P5/4.10.2/doc/tei-p5-doc/readme-4.10.0.html)4.10.2/doc/tei-p5-doc/readme-4.10.0.html.
Edit the P5/VERSION file to the correct number
This file
consists only of the bare version number, followed by "alpha" or "beta":
2.8.2beta
For the release process, you need to remove the letters from
@@ -273,36 +319,52 @@
actual release version number. Get p5subset.xml 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.
- Note: 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 make DIFFNOW=0 test 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.Announce a freeze on pushes to the release branch on the
- TEI Technical Council mailing listCommit your changes to the P5 release branch release-X.X.X.
- Complete the following steps for the Stylesheets (have a stylesheets expert on hand to help debug problems):
-
+ Get p5subset.xml 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.
+ Note: 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 make DIFFNOW=0 test 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.Announce a freeze on pushes to the release branch on the TEI
+ Technical Council mailing listCommit your changes to the P5 release branch
+ release-X.X.X.
+ Complete the following steps for the Stylesheets (have a
+ stylesheets expert on hand to help debug problems):
- Edit the Stylesheets/VERSION number to the correct release number (usually just
remove the 'a').
- - Run
make log to generate the changelog. Then commit the changes.
+ - Run
make log to generate the changelog. Then commit the
+ changes.
+ - Merge the release branch into the
dev branch
+ git checkout dev
+ git merge release-X.X.X
+
+ - Merge the release branch into
released
+ git checkout released
+ git merge --no-ff -m "YOUR COMMIT MESSAGE" release-X.X.X
+
Push your changes for both P5 and the Stylesheets to the git
- repository, git push origin release-X.X.X
and watch Jenkins build P5 for you.
- 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:
-
+ Push your changes for both P5 and the Stylesheets to the git
+ repository, git push origin release-X.X.X
and watch Jenkins build P5
+ for you.
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:
[https://jenkins.tei-c.org](https://jenkins.tei-c.org)[https://jenkins2.tei-c.org](https://jenkins2.tei-c.org)
- 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.
-
- - 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.
-
- - Check for the Stylesheets at
[https://tei-c.org/Vault/Stylesheets/](https://tei-c.org/Vault/Stylesheets/).
- - Check for the Guidelines at
[https://tei-c.org/Vault/P5/](https://tei-c.org/Vault/P5/).
+ - 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.
+
+ - Check for the Stylesheets at
[https://tei-c.org/Vault/Stylesheets/](https://tei-c.org/Vault/Stylesheets/).
+ - Check for the Guidelines at
[https://tei-c.org/Vault/P5/](https://tei-c.org/Vault/P5/).
-
+
- Check out or update a local copy of the source code from
[https://github.com/TEIC/oxygen-tei](https://github.com/TEIC/oxygen-tei) to your local system.
-
- - cd into the oxygen-tei folder (it should contain folders called "frameworks" and
- "jenkins").
-
+
+ - Change directory to the oxygen-tei folder
+ cd oxygen-tei
List the contents of the folder to double check by
+ entering ls. The folder should contain folders called "frameworks" and
+ "jenkins".
+
- Run the ant build process with the "release" parameter:
ant release
This builds the plugin using the latest stable
versions of P5 and the Stylesheets, then offers to upload the result to the TEI's
@@ -505,23 +579,22 @@
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.
-
- - Go to the TEIC/oxygen-tei GitHub repo and create
- a new release, using the
Draft new release
- button. Copy the previous release info (tag, title, and
- text), and tweak the versions as appropriate. The tag
- should be vx.x.x (don’t forget
- the v
!), the title will be Release
- x.x.x, and the text Release number X of
- the oXygen TEI plugin, based on TEI P5 x.x.x and
- Stylesheets x.x.x.
-
+
+ - Go to the
[TEIC/oxygen-tei](https://github.com/TEIC/oxygen-tei/releases) GitHub repo and create a new release, using the Draft
+ new release button. Copy the previous release info (tag, title, and text),
+ and tweak the versions as appropriate. The tag should be vx.x.x (don’t
+ forget the v!), the title will be Release x.x.x, and the
+ text Release number X of the oXygen TEI plugin, based on TEI P5 x.x.x and
+ Stylesheets x.x.x.
+
- Attach the zip file you just created in the build process, which will be named
- something like
oxygen-tei-x.x.x-x.x.x.zip, with the numbers from
- the current TEI and Stylesheets releases.
-
- - Once the tag/release has been published, run
ant uploadOxygenUpdateFile
- to push the updateSite.oxygen file up to the TEI server.
+ something like oxygen-tei-x.x.x-x.x.x.zip, with the numbers from the
+ current TEI and Stylesheets releases.
+
+ - Once the tag/release has been published, run
ant
+ uploadOxygenUpdateFile
to push the updateSite.oxygen file
+ up to the TEI server.
[News](https://tei-c.org/news/)'. The Chair should contact the Social Media coordinator (currently Anna
+ Sofia Lippolis) to help spread the news.
Lift the freeze on committing changes to the repository
Write to the TEI Council list and let them know that they can once again start
committing changes to the repository.Increment the build number for the next release cycle
- 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 ([http://www.unicode.org/versions/](http://www.unicode.org/versions/)) 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.
-
-
-
+ 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
+ ([http://www.unicode.org/versions/](http://www.unicode.org/versions/)) 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.
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:
+ 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:
2.9.0a
signifying that the versions built subsequent to the release
are now in the alpha stage.