When the Jenkins job validation encounters build warnings or errors, it creates an email message to notify the team members configured in the buildConfiguration.json file. The email message lists all warnings and errors found during the build. If the errors are derived from one or more Flare log files, the email message includes a Zip file containing the log files, which recipients can use to troubleshoot and resolve the build issues. This saves authors time by allowing them to debug issues using the build computer's log file, without needing to rebuild the project on their own computer.
Log file warnings and errors typically indicate problems in authoring source files that were introduced by recent author commits to the repository. Errors indicate problems that prevent a target from generating. Examples of problems that generate an error are:
- Checking in merge conflict markers, rather than correctly resolving a merge conflict. In Flare, this generates an error such as:
10086: Build failed: Name cannot begin with the '<' character, hexadecimal value 0x3C
Resolving this error requires editing the affected files, manually removing the merge makers (and merging the relevant content), and then pushing your changes to the remote repository.
- Manually editing any of your authoring tool's source files and introducing coding errors that result in an invalid file.
Resolving this error requires restoring the earlier, valid version of the affected files.
Warnings indicate issues that didn't stop the build but introduced problems that are visible to your audience. Examples of warnings are: removed cross-references (for example, because they linked to a topic that is not included in the output), invalid XML topics (that is, topics with coding errors that prevent the display of their contents), broken related topic links, and missing source files (for example, referenced topics or images that no longer exist).
To resolve log errors
- Unzip the file attached to the email notification that you received. Then, copy the specified build log to a path in your local Git repository that matches the same folder organization listed in the email message. For example, if the email contains a notification of a build error in this log file path:
C:\GitRepo\myProject\Output\BuildAdmin\MyTarget\MyTarget.mclog
Then unzip the attachment, and copy the MyTarget.mclog file to the same folder on your machine, substituting your own user account for the build account in the original file path (in this case, BuildAdmin). For example:
C:\MyGitRepos\myProject\Output\MyUserAccount\MyTarget\MyTarget.mclog
Because the relative path of the log file to its source project on your local computer now matches the relative path of the log file to its source project on the build computer, you can use the log file to troubleshoot warnings.
- Open the log file you copied in the previous step. Opening the file automatically launches Flare.
- On the Errors or Warnings tab, read the description of the problem and then double-click the build issue. In many cases, Flare opens the problematic file responsible for the issue.
If Flare doesn't open the file causing the problem, use the following tips to resolve the issue:
- Click the Messages tab and review what the project was doing immediately before the warning or error occurred. Try opening the Flare files related to that task and look for problems. For example, if the last thing Flare did was generate a specific topic file, open that file and check for issues that might be responsible for the build problems.
- In Flare, use the Find/Replace tool to search across all topics and check for merge conflict markers that an author might have accidentally checked in (that is, search for <<<<). Be sure to select Find in source code in the search options.
Using these strategies, you can quickly find and fix issues that introduced build warnings or errors, without ever needing to perform a local build of the project.