ReleaseProc

EpiDoc Release Process

• EpiDoc Release Process
  • What you need to know about the EpiDoc release process
  • What triggers a release
  • How to make a release
    • Release Day -28: Announce release schedule (preferably a Tuesday)
    • Release Day -15: Last call for edits (preferably a Monday)
    • Release Day -8: Call for testing (preferably a Monday)
    • Release Day -5: Candidate release (preferably a Thursday)
    • Release Day: Final release (preferably a Tuesday)

When making a formal, stable release of the EpiDoc Schema, Guidelines, Reference Stylesheets and EFES, the following policies and checklist should be followed.

---

What you need to know about the EpiDoc release process

Each release will be led by a team of two (or sometimes three) “release technicians,” at least one of whom should be new to this process. The technicians do not need to understand how the process works or how to build and run GitHub Actions; ability to push to Git, including branches and tags, is all that is needed.

The release process is currently managed using GitHub actions which automate most of the process. For more information, see here.

• The /latest/ websites for Guidelines and Schema reflect only the most recent, stable, numbered releases of these parts of the code. These are programmatically generated from the tagged release process (see below) and should not be directly edited or pushed to at any time. The “latest” pages are used in production, including by many external projects, and should be treated with respect!
• The /dev/ sites for Guidelines and Schema are automatically generated from content pushed to the Main branch of the Source repo on GitHub. The “dev” pages reflect in-progress, experimental, or testing versions, and may be unstable. Only intrepid users will use them in production.

---

What triggers a release

1. If the schema is updated a release of all four EpiDoc components should be compiled.
2. The schema is updated:
   a) whenever the TEI schema and Guidelines are released (currently about twice a year);
   b) when a change agreed on the Markup List, a ticket sprint, or project meeting involves loosening or tightening the menu of allowed elements, attributes, values or content in a certain context;
   c) when a new community's practice is incorporated into EpiDoc usage.
3. 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.
4. Most releases are minor, and should be reflected by incrementing the second part of the release number, e.g. "9.5" to "9.6".
5. 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 EpiDoc's 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

Release Day -28: Announce release schedule (preferably a Tuesday)

1. Distribute to the Markup List an announcement of the release timetable. An example of a release timetable email can be found here.

Release Day -15: Last call for edits (preferably a Monday)

1. 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

2. Align ODD with TEI: Edit the EpiDoc ODD (tei-epidoc.xml) and make sure that it is referencing the current or otherwise selected TEI schema <schemaSpec ident="tei-epidoc" docLang="en" prefix="tei_" start="TEI teiCorpus" xml:lang="en" source="https://www.tei-c.org/Vault/P5/4.7.0/xml/tei/odd/p5subset.xml"> (l.190-191 as of release 9.6). Commit and push the change to GitHub. This triggers publication of your changes to the dev version of the Guidelines visible on the web. 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 parameterized handling of it in XSLT as appropriate.

3. Create a branch of EFES code in Github, with the current version of EpiDoc Reference Stylesheets copied into the directory at /webapps/ROOT/kiln/sylesheets/epidoc

Release Day -8: Call for testing (preferably a Monday)

1. One week into the release cycle (day 7) all development on the Guidelines, XSLT , ODD, and EFES should be frozen, pushed to Git (which updates to dev), and only proofreading and bug-fixing take place for the next three days.
2. Notification of this "call for testing" should be posted to Markup. An example email can be found here.

Release Day -5: Candidate release (preferably a Thursday)

1. Five days before release all changes to the code should be pushed to GitHub, updating the dev branch. The candidate release should be frozen at this point, unless a major error is identified.
2. Release Notes: A list of significant changes to the ODD/Schema, Guidelines, Stylesheets, and EFES since the previous release should be compiled and added to a new dated section at the top of Source/ReleaseNotes.txt (this file is directly inside the GitHub repository, at the same level as the 'guidelines' and 'schema' folders). You may consult the GitHub commit logs for Source, Stylesheets and EFES and the <revisionDesc> of the ODD (tei-epidoc.xml), but be judicious and summarise minor changes rather than copying everything. To see the Git log, you can type git log in the terminal or, if you want to see every file which has been changed to figure out what the comments refer to, use git log --name-status. Or you can find commit logs through the Github code page, or the Github Desktop interface. Commit the modified ReleaseNotes.txt file to Git, and push to GitHub.
3. New Guidelines: Change the <seg type="version"> in the titleStmt of driver.xml to read 9.xx candidate. (This text should read candidate before being uploaded to dev; as noted below it will be changed to 9.xx on Release Day and immediately after to post-9.xx dev). Commit the change and push it.

   Change the bibliographic citation in the Guidelines (toc.xml) so that the date range ends with the year of the current release. (NB: version 9 should be dated from 2017–current year).

4. New EFES: re-copy (if changed) current version of EpiDoc Reference Stylesheets into the EFES directory at /webapps/ROOT/kiln/sylesheets/epidoc, commit to the branch, and issue a Pull Request to merge this into the head version of EFES.
5. Email: Send an email with links to the new (numbered) schema release, (dev) Guidelines, Reference Stylesheets, and EFES branch to the Markup list, with the summary of changes from ReleaseNotes.txt, and ask users to check for changes, incompatibility and/or other technical problems against their EpiDoc XML in the next 4 days. A sample email can be found here.
6. Also email EFES Users about the EFES branch, and ask one of the EFES devs to manage the pull request in a few days.

Release Day: Final release (preferably a Tuesday)

If there are no complaints or bugs by the time of the deadline, proceed with the final release using the following steps.

1. Prepare the Schema for release by inserting a milestone <change> element at the top of the <revisionDesc> of the ODD file (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>, commit the modified file to Git.
2. Prepare the Guidelines for release by changing the <seg type="version"> in the titleStmt of driver.xml to read 9.xx, deleting the word “candidate”, and commit the modified file to Git, then push it.
3. Tag the current revision of the Schema and Guidelines with the current release number. with the current release number, (i.e. run git tag v9.xx). Make sure that you don’t forget the “v” before the release number. Push the tag to GitHub using git push --tags. This tag can also be implemented using GitHub Desktop.
4. Tag the current revision of the Stylesheets in the Stylesheets repo using the same git commands as in the previous step. This will trigger the merge of the “main” repo into the “latest” branch, which in turn will generate the “latest” version of the guidelines and schema on the web. No further action is necessary. Please don’t try to update the “latest” branch.
5. On the GitHub release pages for the Source (Guidelines and Schema) and Stylesheets repositories, check that the list of releases includes the version that you’ve just pushed.
6. Check that the web version of the Guidelines displays the correct version number.
7. Accept the EFES pull request as discussed with the EFES community.
8. Modify wiki pages in SourceForge to reflect the new release.
   a) Modify the Latest Release wiki page to address the new release, as follows:
             i) For the Guidelines, link to the new release version online at Stoa.
             ii) For the Schema, link to the new release version online at Stoa.
             iii) For the Reference Stylesheets, link directly to the newly created release in the GitHub repository.
   b) Modify the link to the Latest Release wiki page on the Wiki page by updating the release number.
   c) Modify the EpiDoc Schema page to reflect correct version number.
9. Update the following readmes and web pages to include current year as end-range of bibliographic citations:
   a) EpiDoc Stoa webpage, for which you will need to modify Source/README.md
   b) SourceForge wiki
10. Prepare the Guidelines for future development by changing 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").
11. Publicize the new release by writing to the Markup list again, informing them of the last four points (updating of /latest/ folder; GitHub tag; GitHub release downloads; updated Stylesheets. A sample email message can be found here.
12. If a critical bug is found at any time after the release an emergency release should be uploaded as soon as possible following an abbreviated procedure 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, Schema or Stylesheets will begin to build content toward the next release.