Building the gh-pages on Travis-CI about wcag HOT 3 CLOSED

1. I think that having the master and the working branch would be good, although the process that we have defined will result in the changes made on the working branch being merged into the master as the final step of publication following the public review. But being able to look at the XML and easily refer to the HTML version for the master branch may be of use to in some way? I'm not sure. If it is easy then we'd do both, if not, the working branch takes priority. We also have the content of the "techniques" directory which are just example files that are edited as HTML/CSS/whatever and we can route to a gh-pages directory without transforming.

Question for Michael - perhaps we should set up the gh-pages transform so that it also points to the gh-pages version of the live examples?

2. I'm not sure. Michael?
3. I'm not sure because I'm not certain how people will ultimately use this. Perhaps this is a nice to have?
4. Michael will be better able to address this as he made the XSL transform files.

from wcag.

Q: What content branches should be built out

A: I'm a little on the fence but lean with AWK towards building arbitrary branches, so there would be a gh-pages version of each built branch. That way you can see the commit you just made in your branch, while not disturbing other branch builds. At the moment that is less of a concern as there is only one branch of real interest, the working branch (the master branch being already reflected on the W3C server). But that could change, so the flexibility is probably good.

Q: Should the publishing be handled as an Ant target or a Bash script

A: I think an Ant target, if that's feasible. One big reason for that is that, when publishing to gh-pages, the build needs to know the published URI the documents would appear at, in addition to knowing the output path. This is so cross references between Understanding and Techniques will work correctly. As it stands right now, the URI comes from a value in the XML files themselves that we update only when we publish, so cross references would come out to some random W3C URI. It would be easy to get confused looking at the gh built version and find yourself on (not even necessarily the latest) W3C version the moment you follow a link.

I suggest we create an Ant target specifically for GH building, and call that target from the YAML file. I think a starter version of the target would look like:

<target name="gh-pages">
    <antcall target="understanding">
        <param name="outputdir.understanding" value="Generated/Understanding"/>
        <param name="publoc.understanding" value="http://w3c.github.io/wcag/BRANCH_NAME/Understanding"/>
        <param name="publoc.techniques" value="http://w3c.github.io/wcag/BRANCH_NAME/Techniques"/>
    </antcall>
    <antcall target="techniques">
        <param name="outputdir.techniques" value="Generated/Techniques"/>
        <param name="publoc.understanding" value="http://w3c.github.io/wcag/BRANCH_NAME/Understanding"/>
        <param name="publoc.techniques" value="http://w3c.github.io/wcag/BRANCH_NAME/Techniques"/>
    </antcall>
</target>

There would probably be some additional parameters to pass, and I would have to modify some other targets to support the publoc params while not breaking our W3C builds, but it's the basic idea.

Q: Should history be maintained on the gh-pages branch or keep it as a single commit orphan branch

A: I lean towards a single commit orphan branch. I don't see a value to maintaining a history of the built version, since the history of the sources is what really has meaning to us. That said, perhaps a use case is people want to compare versions. So if it's not expensive, I don't object to it being a full-fledged branch, just recognizing that from time to time things might change drastically.

Q: How to integrate in the required CSS/JS for the pages

A: The first option that comes to mind is just to stick a copy in the gh-pages branch and leave it, and try to remember to update it as needed. But if that's not realistic, I suggest we have the Ant target copy it in with a task. I guess that means we have to put those resources into the repository as well (not a problem, just hadn't done it).

from wcag.

Preparing to mark as deferred due to inactivity and group resource constraints (https://www.w3.org/WAI/GL/wiki/Handling_Issues).

from wcag.