Meeting minutes 2018 02 01

Attendance: Robert Anderson, Jarno Elovirta, George Bina, Radu Coravu, Frank Wegman, John Pashley, Shane Taylor, Roger Sheen,

Item 1: Any updates about prior releases?

3.0.2 patch status: https://github.com/orgs/dita-ot/projects/2

Has quite a few items in it, fixes from Jarno and Robert, focus on NPE issues. One new NPE issue is related to chunking and probably a big item, but has a workaround so not going to hold the patch for it. Still item open about unsupported characters in the file path, if small enough Jarno will try to handle this week, then good to release.

Roger: just pushed updates to release notes for items in there already, still open until we close the patch. Have other changes planned but going to target develop branch with those.

Plan: release patch on Monday.

Thoughts on 2.5 patch: still not sure if/when, if we open a branch Robert plans to port a number of smaller fixes back to that release.

Item 2: DITA-OT 3.1 Development status and updates

3.1 project board: https://github.com/orgs/dita-ot/projects/1

Reminder: for anybody who wants to try out coding, there are still a bunch of items in the backlog marked with good first bug -- easy way to get started with coding for those who want to get involved. Have those in the 3.1 "to do" list in the project board.

• Robert has a likely fix for a PDF issue from Radu's backlog list (empty part element that functions as topicgroup)
• Jarno working on better support for ditaFileset method of calling routines from Ant. Adding a notation in the job file set to indicate that a file is an input file (such as the starting root map) - should now allow you to do all functions from Ant using dita fileset, to process all topics, all maps, just input map, etc. Problem is, it doesn't seem to be supported in Ant's on <xslt> task, so have to tweak the way we call it to use our custom <xslt> module. Additional benefit: allows use of Java extensions when using XSLT. Could also start caching XSLT template objects at Java level; so when you run DITA-OT, could keep cache of compiled XSLT, slightly speed up Saxon calls because they don't need to recompile each time.
• PDF plus Chunking:
  • Have had several discussions lately about chunking and PDF. For nearly every case, it's unnecessary - turning many DITA topic documents into one topic document in preprocess is meaningless when they will all end up in the PDF in the same order.
  • Only concern is for edge cases. Robert has not seen those in actual documents, only test documents, but Robert has a very specific audience so they could really exist. Edge cases include -- publishing one large DITA document with lots of topics, but with chunking, attempt to select a single topic or branch within that document for publishing without using the rest of the document.
  • Jarno notes: we may not be fully to spec on some of these items due to old / bad code + old / bad descriptions in spec. It's possible that some CMS systems have based their chunking support on our bugs / our algorithms rather than on the spec. Robert thinks more likely for other parts of toolkit because chunking is just so unreliable.
  • Roger notes: could also add chunking into our docs, explaining where we extend / differ from the spec. Jarno agrees, if we change behavior, good to add info there.

Item 3: Doc updates and plans, update on documentation call

Release notes for 3.0.2 about ready.

For 3.1: planning new section on "coding for DITA-OT" -- describe coding best practices for plugins / extensions, such as using the ditaFileset when calling routines from Ant.

Had been discussing: Do we need to call people's attention to XSLT 2.0 requirement, as part of coding conventions? With latest Saxon that's no longer a hard requirement (9.8.0-5, shipped in 3.0.1, required this update; 9.8.0-7 backtracked, so with that update it's no longer required). But Saxon does still intend to drop that support again some time so it should be listed as a best practice for us.

Our docs build after 3.0 was switched from Ant to Gradle (thanks to pull request from Eero). But that build isn't working with dist build. Sometime between now and 3.1, need to remember to switch that build as well.

Regular docs calls: no decision yet on whether to continue monthly, or have more frequent short calls. May just want to sync up in this call or in Slack.

Item 4: Other topics

• Jarno tightened GitHub branch protection settings.
• Thinking about adding a set of end-to-end tests. Right now have Unit tests (individual pieces of Java or XSLT code), and integration tests (run DITA-OT from start to either end of preprocess or end of XHTML, and compare). Those are only useful for outputs where we can compare outputs - compare XML or XHTML / HTML5. Theoretical support for PDF could be done to validate content but haven't done so yet. New thought: single large set of DITA docs that doesn't test everything, but is generally pretty extensive. Run it with every out-of-the-box transformation type. Don't actually compare output, but verify process still runs, no new errors, same output files generated.
  • Lots of discussion. Others also asking for more comparison of output, based on large doc set.
  • One thing that has presented problems, and is likely of most concern to user community: how to test "I've updated toolkit and put in my plugins, does my output still look the same"
  • Robert would like to open up a new channel in Slack team devoted to testing - to discuss any/all aspects, from our own unit test coverage up to that end-user concern.
• Now using project boards: https://github.com/orgs/dita-ot/projects/
  • Experimenting with project boards now - if we like it, we'll keep using, if not, don't have to use for future releases / patches. Note: this is an organization level project, not project, so it can cover DITA-OT repo, docs, etc.
  • Working out our conventions for project boards now. Goal: do not assign an issue to a milestone until it's done (previously we often set Milestone to indicate a goal, but that could be misleading). Putting an issue into a project board signals intent; putting it in Milestone indicates release plan.

Item 5: Backlog discussion

Time to go through pull requests, issues tracker, determine how to handle open issues.

Radu's got a good starter list for backlog discussion of important issues that are still open (or were as of this meeting, one is closed and crossed out): https://github.com/dita-ot/dita-ot/issues/2528