When making a formal, stable release of the EpiDoc schema, Guidelines and stylesheets, the following policies and checklist should be followed.
What triggers a release
- If the schema is updated a release of all three EpiDoc components should be compiled.
- The schema is updated:
- whenever the TEI schema and Guidelines are released (currently about twice a year);
- when a change agreed on the Markup List or in a project meeting involves loosening or tightening the menu of allowed elements, attributes or content in a certain context;
- when a new community's practice is incorporated into EpiDoc usage.
- If a significant change in the Guidelines or XSLT behaviour has taken place (whether or not it requires an ODD or schema change) this may also trigger a release, if it is considered important enough to be flagged to the community.
- Most releases are minor, and should be reflected by incrementing the second part of the release number, e.g. "9.1" to "9.2".
- A major release would normally involve a re-engineering of the Guidelines structure or some other technical feature. For example, the change from "7.x" to "8.0" was triggered by the move from TEI P4 to TEI P5 in 2009. A major release should be reflected by incrementing the first part of the release number, and returning the second part to zero, e.g. "8.19" to "9.0".
How to make a release
Day 0: Last call for edits (preferably a Monday)
- At the start of the two week release cycle (day 0) write to Markup to inform the community that a release is imminent, and any changes that have been brewing should be made asap. An example of a Last Call email can be found here
- If an element is added, removed or modified in the ODD (or a change inherited from TEI), the Guidelines and Stylesheets should be checked to ensure consistency, and updated if appropriate. At the very least add one example of any new or changed element to the Guidelines, and offer parametrized handling of it in XSLT as appropriate.
Day 7: Call for testing (preferably a Monday)
- One week into the release cycle (day 7) all development on the Guidelines, XSLT or ODD should be frozen, and only proofreading and bug-fixing take place for the next three days.
- Build and upload current versions of Guidelines and Schema to the appropriate dev directories on Stoa.org, so that people have a stable copy to proofread and test their code against, respectively.
- Notification of this "call for testing" should be posted to Markup. An example email can be found here.
Day 10: Candidate release (preferably a Thursday)
- Five days before release all changes to the code should be frozen unless a major error is identified
- Release Notes: A list of significant changes to the ODD, GLs and XSLT, since the previous release should be compiled and added to a new dated section at the top of
/trunk/ReleaseNotes.txt (this file is directly inside the SVN repository, at the same level as the 'guidelines' and 'schema' folders). You may consult the SVN commit log and the
<revisionDesc> of the ODD (tei-epidoc.xml), but be judicious and summarise minor changes rather than copying everything. To see the log, you can use from command line
or if you want to see every file which has been changed to figure out what the comments refer to, use
svn log --verbose
- New Schema: If a new schema needs to be generated as a result of ODD changes, or intervening TEI release, use
tei-epidoc.xml as the file in OxGarage. To generate the new version of the schema, follow the instructions in trunk/schema/README.txt.
- Also using OxGarage, generate a "Compiled ODD Document" from
tei-epidoc.xml and save this as
- Ask someone with upload rights in Stoa (Gabby, Tom, Hugh, Ryan) to create a new directory at
www.stoa.org/epidoc/schema with the value of the new release (as determined above), and to place a copy of the ODD, Compiled ODD, RelaxNG and README in that location. Similarly, update
- New Guidelines: Change the
<seg type="version"> in the titleStmt of driver.xml to read 8.xx candidate (with current version number in place of "9.xx"). This file should read candidate before being uploaded to dev, then it will change to 9.xx on day 13 and immediately after to post-9.xx dev.
- To generate the new version of the Guidelines, follow the instructions in trunk/guidelines/README.txt. This generated HTML for you to check, but should not be committed to svn. The user with upload rights will generate them locally as well.
- Note that if the main schema is changed, tei-epidoc-example.rng should also be updated (instructions for which are in trunk/guidelines/README.txt).
- Ask someone with upload rights to copy the new version of the Guidelines HTML to
www.stoa.org/epidoc/gl/dev/, replacing the current version there.
- Email: Send a link to the new (numbered) schema release and (dev) Guidelines to the Markup list, with the summary of changes from
ReleaseNotes.txt, and ask users to check for changes, incompatibilty and/or other technical problems against their EpiDoc XML in the next 4 days. Ask also to the users of the Example XSLT to test them again if any changes have been made.
- Advance notice: please make sure that the release tech is a member of "Tracker administrators" and "Release technicians" groups, and that they have permission to upload files to the file download area, well in advance of the final release, since these permissions can sometimes take several hours to propagate.
Day 15: Final release (preferably a Tuesday)
- If there are no complaints or bugs by the time of the deadline, proceed with the final release.
- Insert a milestone
<change> element at the top of the
<revisionDesc> of the ODD file (
/trunk/schema/tei-epidoc.xml) indicating the current version number, the date, and the TEI version under which the release was generated. E.g.
<change who="#PY" when="2017-03-14">release 8.23: Aligned schema with TEI v. 3.1.0</change>
- Ask someone with upload rights to copy the new schema etc. from the numbered release directory to
www.stoa.org/epidoc/schema/latest. Ask them also to generate a new version of the Guidelines HTML (with any corrections applied since the candidate release if necessary). For this run only, change the parameter
$analytics to "on" in the EpiDoc P5 Guidelines HTML Oxygen scenario (mutatis mutandis if running on command line), so that GoogleAnalytics is applied to the latest GLs. Change the parameter back to "off" after the final run. Remember to change the
<seg type="version"> in the titleStmt of driver.xml to read 8.xx (with current version number in place of "8.xx"). (After the release, this version number should be changed to "post-8.xx dev".)
- If a major release (e.g. "8.x" to "9.0"), first create a new directory at
www.stoa.org/epidoc/gl/ with the value of the previous release (the highest increment of the second part of the number), and move the contents of the previous "latest" Guidelines output to that location. Place a copy of the new Guidelines in the "latest" directory.
- If a minor release simply copy the newly generated Guidelines to
www.stoa.org/epidoc/gl/latest (overwriting or deleting the previous version).
Tag the current revision in the EpiDoc SVN with the current release number. (i.e. copy the schema, guidelines, and epidoc-p5-xslt directories, as well as ReleaseNotes.txt, into a new directory at
/tags/<release-no>, using a GUI or the command line)
- you can create the new tag directory at the command line with a "svn mkdir" command
- if you are not using a GUI, from the command line, once the folder has been created you can enter a command like the following for each of the three folders you want to associate with the new tag (and also for trunk/ReleaseNotes.txt):
svn cp https://svn.code.sf.net/p/epidoc/code/trunk/guidelines https://svn.code.sf.net/p/epidoc/code/tags/9.0 -m'tag guidelines for release 9.0'
Follow the instructions below to create a ZIP archives of epidoc-p5-xslt and upload it via the SourceForge File Release System
to the Example Stylesheets folder in the EpiDoc file system on SourceForge.
- Make sure you have been added to the user group of the release technicians to be able to click the ADD button mentioned below when time comes.
- Use svn export against the rev number associated with the current release tag to get a clean directory tree. This will mean, if you are not using a GUI, to enter a command a like this:
svn export https://svn.code.sf.net/p/epidoc/code/tags/9.0/example-p5-xslt NameOfYourFolder
- In the exported copy of the folder you will have guidelines, xslt and schema which you have uploaded. Rename the example-p5-xslt directory by appending the current release number sequence, e.g., example-p5-xslt-9.0.
- ZIP the renamed directory such that the resulting archive shares the same name, with the addition of a ".zip" extension. Delete any other files from the directory (such as Mac OS
- Navigate to the Example Stylesheets folder in the Sourceforge File browser and use the "Add File" button to upload the ZIP file.
- Once the file is uploaded, click on the "info" icon to the right of the newly uploaded ZIP file (small italic "i" inside a gray circle) and click "select all" to make this file the "default download" for all operating systems (this sets the "latest download" prompt throughout the Sourceforge File Release system for the EpiDoc project.
- Upload also the schema on the schema download page, as well as the Guidelines, zipping the files from the exported folder.
- Change the
<seg type="version"> in the titleStmt of driver.xml to read post-9.xx dev (with current version number in place of "9.xx").
- Modify the [LatestRelease] wiki page to address the new release, as follows:
- For the Guidelines, link to the new release version online at Stoa.
- For the Schema, link to the new release version online at Stoa.
- For the Example Stylesheets, link directly to the ZIP file that was uploaded to the Sourceforge file release area in the preceding step.
- Also modify the link to the Latest Release wiki page on the Wiki [Home] page by updating the release number. Update the number also on the EpiDoc Schema page.
- Write to the Markup list again, informing them of the last three points (updating of
/latest/ folder; svn tag; Sourceforge download package).
- Ask one of the EpiDoc Facebook Page admins to announce the new release on Facebook, with a link to the [LatestRelease] wiki page.
- If a bug is found at any time after the release an emergency release should be uploaded as soon as possible following an abbreviated procedure (only day 15) and it should be numbered 9.xx.1. In the email to the list the bug should be reported for users of the downloaded version to check if they have been affected.
Any further changes to Guidelines or ODD or XSLT will begin to build content toward the next release.