Automation: Guide Examples

Maintaining documentation/guides have a couple of common issues:

• copy/paste of source code into the guide docs manually
• untested source code examples
• in time, the examples/guides are referring to old software versions

We want to eliminate these issues and automate the process where possible.

Arquillian Awestruct Solution:

• pull example source code directly from master branch on github
• execute a full source code build via Maven including tests
• pull in source code snippet into the documentation from the source

This assures the examples are working and no code duplication is required. The next step is to tackle the 'out of date' examples.

When we are running the Arquillian Site Pipeline, we have info about all released artifacts. After pulling the github example source and before we build it, we validate if the examples are using the latest version. If latest version is found simply move on to build.

If it is not the latest version, update the examples pom with the latest version. Now when we build it, we are verifying that the examples are working using the current releases. If the Maven build pass, we are good to move on and generate the guide. But we are generating the guide based on a changed example source, so we will branch the local repo, add/commit the changes, push it back to github and open a pull request to update the example source(in time this could push directly to examples master as well). If the build on the other hand fail, we have a clear indication that 'something' in the example code is out of date and probably both the code and text needs updating. In this scenario we will automatically create a 'bug' report in Jira: Guide XX require manual update for Arquillian-Core 1.0.0.CR8.

• find latest version
• update example pom
• build example code
  • if ok, push changes to github and open a pull request for the changes made
  • if error, open a jira for updating the source / guides

Toughts

• we could possible ignore the pom file of the example source and use JBossForge + Arquillian plugin to regenerate it, with the assumption that the Forge Arquillian Plugin will know how to correctly setup the new Arquillian version?