We maintain a set of maintenance releases for TextGridLab 2.0
WORK IN PROGRESS
Bug Fixing / Development
- Everything that needs to be fixed for a 2.x release needs a proper focused issue report in ChiliProject.
- Bug fixes should be applied to a topic branch (feature/issue) and be merged into the
developbranch first, unless we are in a release phase (see below). Small issues can also be implemented first and
- Each commit should be focused, it MUST mention a short summary about the commit, and it SHOULD mention a the relevant issue number (#12345) in its commit message:
resolves #12345to automatically resolve the issue
references #12345to add a link between issue and commit in the issue tracker.
- You should increase the relevant artifact versions accordingly
- If your bug should be included in yet unreleased TextGridLab 2.n, include the relevant release in the bug reports fix for field
We use the git flow model (and the corresponding tools), or an approximation thereof: New development generally happens in the
develop branch, when we create a new release (e.g., 2.1), we fork a branch
release/2.1 off the
Preparing the Release Candidate
In preparation of the release candidate, it is best to work on the aggregate
textgrid-laboratory project to deal with all components (= submodules) in parallel.
- Clone the repository, and all its submodules, to a new folder called
- change into that directory
- checkout the
- initialize the git-flow tooling for the top-level project
- start the release branch, this effectively creates a new branch called
release/3.3and checks it out
- do the same steps for all submodules
- register the branch names; this allows you to do
git submodule update --remotelater to get them to the tip of their branch
- commit the changes
Now we should adjust the version numbers at the various places in the source code. Additionally, we should set the application name to "TextGridLab RC" to indicate it's a release candidate. There is a shell script in the textgridlab-modules project for that:
Publish the release branch:
Now Jenkins should start building RC on https://ci.de.dariah.eu/jenkins/view/TextGridLab/ and and a lab-3.3rc dir (updatesite) should show up in https://ci.de.dariah.eu/p2/ . It is possible that the order of the builds is not fine on first run, and triggers are failing. Try to get this fixed by: re-running the job 'lab-dependencies' in Jenkins. Trigger the " " button in Jenkins for builds without release-job. Fix the jenkins release build in future!
Once Jenkins is done the rc build pipeline should be in place.
Testing the Release Candidate
After the build with all included releases has finished, the RC should be tested
- Manual test against the features
- Functional test
- Test updates from previous lab version by
- downloading a clean copy of the previous version of the lab
- adding the update site
- Check for updates or restart the lab
- Call for user tests
When everything is tested we need to finish stuff in git, prepare the update site, upload the product zips and update the download website.
- in the
basemodule, update the update site enabledness state in
info.textgrid.lab.feature.base/p2.infto the following settings:
- stable: enabled
- beta: enabled
- nightly: disabled
- prerelease: disabled
- Run the version script again:
./set-version.sh 3.3.0to remove the 'Special Version' and generate the welcome screen look for the released version.
- commit the changes, update the submodule in the
Release in Git
The git flow workflow's release finish feature performs the following steps:
- the release branch is merged into master
- this is tagged
- the master branch is merged into develop
- the release branch is removed.
These steps have to be performed in every submodule, then the
textgrid-laboratory module needs to be updated, then this needs to be released. If we're using an older working tree, we should make sure all branches are up-to-date:
Now, we need to make sure the nightly branch does enable the nightly update site. To do so,
git checkout develop
info.textgrid.lab.feature.base/p2.infto enable the Nightly update site (two lines)
- cd ..
- ./set-version.sh 3.4.0 Nightly
- cd base
- check the changes, remove unwanted modifications e.g. 'meld .' or 'git diff'
- git commit -am "Started 3.4.0 development cycle"
git checkout master
If everything above went cleanly, now push the submodules
Now commit the submodule updates in the
textgrid-laboratory module, still in the
release/3.3 branch, perform the release there, and push the master branch:
The prerelease jenkins job should now build the actual release version off the master branches. Look into the dashboard, all release/3.3 branch builds should be gone, trigger a scan if not.
Wait for the final base build to finish and test it, and then go on to publish the released version.
Prepare the Update Site
- The update sites are maintained on textgridlab.org in
/var/www/nginx-root/textgridlab.org/updates/stable. We have the following directory structure:
stable/composite/2.0.5etc. each contain an update site for the respective version only.
stable/compositeis an composite update site of all these version-specific update sites.
stableis a (non-composite) mirror of
To prepare this, there are a bunch of scripts linked to /usr/local/bin. Do the following, in this order, replacing 3.3.0 with the appropriate version:
generate-aggregate-repo https://ci.de.dariah.eu/p2/prerelease/base 3.3.0– this will mirror the repository from the integration build to the directory
generate-composite-p2-repo "TextGridLab Stable" .*– this will create the composite repository metadata for the 2.* and 3.* subdirectories in the current (composite) directory.
generate-aggregate-repo $PWD/composite candidate– this will create an aggregate (= faster) mirror of the composite stuff in the
For each directory or file in
candidate, remove their respective counterpart from
stableand move the version from
remove the (now empty)
- Details for managing the directory structure and the
composite*.xmlfiles are at Update Site Management.
Prepare the Downloads
- The download site is on textgridlab.org at
/var/www/download. Files are in subdirectories with the version number
- It is probably best to just mirror the original downloads from the automatic build
- on textgridlab.org, cd into
/var/www/download/2.0.2and run the generate-lab-index.py script
- open the download page in the typo3 backend and
- paste the generate-lab-index.py output into the download table field in the hero block, replacing the existing content
- write a short release note in German and English into the corresponding field
- generate the changelog
in Jira: go to the TextGrid project's Versions list click the version to release click the Release Notes link in the upper right
- paste the changelog into the corresponding field in typo3
- add last version to the list of archived versions
According to the git-flow model, we have regular development in
develop and in
feature/xxx branches which get merged into
develop, release preparation branches called
release/<Version>, and a stable
master branch that features just the releases. Regular releases follow the following workflow:
develop → branch
develop → test & last bugfixes → release: (merge
master → tag master as
2.1 → merge master (or rather the tag) back into
develop (for each module, and for the umbrella project
However, it might be neccessary to apply just one or two bug fixes to the current release version and to publish the fixed version rather fast. To do so, git-flow supports the notion of hotfixes. Hotfixes branch off the latest released version (= master branch), perform the fixes, and then get merged into master as well as develop. Here it is explained for a case with a slight modification in the
base module (I forgot to disable the nightly update site for the 2.1 release):
Now you shoud cd up to the umbrella project, run
./build-locally to compile the fixed version, and test (the products can be found in subdirectories of
base/base-repository/target/products after the build). When everything is fine, you can release the hotfix, first in the submodule, then (commit the modified submodule first!) in the umbrella project.
Now you need to push the changes:
The prerelease build will build your hotfix. Afterwards, upload the hotfix release and update the update sites as described above.
- What to do with the parent pom in the different steps of the release / development cycle? it contains the repo locations, and should possibly also have mathching releases and snapshots.