Resolve Validation Errors

Whenever you submit a pull request or commit to master, two validation checks occur:

  • (Git) Check for conflicts between the master branch and your content
  • (Jenkins) Check to make sure your content is well-formed

Whenever a pull request to master is created, GitHub checks for merge conflicts as part of its built-in functionality. In addition, we have extended GitHub to run a series of tests on the code using the Jenkins platform to see if content can be published without problems.

When you submit a pull request, you can see the status of these checks on the pull request page:

validation success image

In this case, both validation passes were successful. When that happens, you can merge your pull request. If one or both of these validation passes fail, this article explains how to fix the errors.

Resolve Jenkins validation errors

The Jenkins validation check makes sure that your content is propertly formatted before it goes through the pipeline and into preview.

Jenkins and validation overview

Jenkins is a popular open-source automation server. It is responsible for testing and deploying all changes that are made to our markdown on GitHub.

Pipelines - Jenkins is made up of pipelines. In Jenkins, a pipeline can be any kind of workflow. For our documentation, a pipeline represents the workflow of taking changes created in a pull request, building them, testing them, and uploading them.

Jobs - Each pipeline has jobs associated with it. A job is an execution of the pipeline. Each job is recorded so that there is a detailed log of all jobs processed.

There are currently two types of jobs (_stage is not yet available):

  • _exl-pr job - When you submit a pull request, a <repo>_exl-pr job kicks off.
  • _exl job - Any commit to master results in an _exl job running. The entire set of files is validated, and, if validation checks pass, the content is uploaded for preview: https://experienceleague.corp.adobe.com

View Jenkins reports

  1. Open Jenkins using one of these methods:

    • In the Git pull request, click the Details button. (Or Command-click Details to open it in a new tab.)

    details image

    • Go to the Jenkins landing page, select either the exl or exl-pr tab, and click the link to your repo. Under “Build History” click the link to the build you want to look at.

    Jenkins build history link

  2. Open the summary.txt file to view the errors.

    In some cases, the summary.txt does not display the error. If that happens, you might need to go into the Console Output log and dig around to find the error. Or contact the SCCM team.

NOTE

We’re currently working on providing validation reports that are easier to locate and use.

Preview failures

In some instances, your job shows up as red even though there are no content errors. These ‘false failures’ are caused when the job times out due to an outage or update in the pipeline. If you see that everything passes except for preview, it’s usually the result of a timeout failure.

timeout failure

If this happens, try running the Rebuild job in Jenkins. If the rebuild job still fails, let the SCCM team know that preview is failing.

TIP

If everything passes except for preview, you can still run the activate-exl job in Jenkins to publish your content.

Understanding Validation Errors

Validation checks to make sure that you don’t have any broken links and that you’re using valid Markdown syntax.

When you get a validation error, open the summary.txt file to see what needs to be fixed. The markdownlist.log is also useful; it displays only the markdown syntax errors.

validation

If this occurs, open your job and choose Rebuild. If the problem persists, contact the SSE team.

Links to images or markdown files that cannot be resolved are failures. Failures stop validation. You can view these broken links in the summary.txt file.

Absolute links to URLs are not checked for validation by default. However, the absolute links might result in broken or unsecure links. We recommend that you check for absolute link errors periodically by running a full link check.

To check absolute links:

  1. Open your repo in Jenkins.

  2. Choose Build with Parameters.

  3. Select the FULLLINKCHECK check box (and REPORTONLY to generate only the log file without deployment).

  4. Click Build.

    This job takes much longer to run with FULLLINKCHECK selected.

  5. When the job finishes, open the summary.txt file or navigate to the linkcheck.log file.

  6. Fix your broken links by doing any of the following:

    • Edit links that are flagged as errors.
    • Put sample website links (such as www.mysite.com) in code blocks so they aren’t rendered as links.
    • For valid websites that are being flagged for some reason, add them to the exclusion list file (linkcheckexclude.json) in your repo.

Markdown syntax errors

Most of the errors you see in this section are self-explanatory. You get the Markdown filename, a description of the error, and the line number where the error occurs. See the Syntax Style Guide.

To fix this, open the file containing the error. Make sure that you open the file in your branch if you submitted a pull request, not in master. Then edit the file and commit the changes to your branch. Committing the change to your branch automatically triggers a new validation job.

Here are the most common Markdown validation errors we see (feel free to add your favorites):

  • Skipping heading levels (from # to ### or ## to ####)
  • Not adding lines before and after headings, fenced code blocks, lists, and other multi-line elements.
  • Multiple titles (# Text) in same article.
  • Using different characters (such as * and + or -) for bullet lists within the same article.

Markdown validation technical details

We use markdownlint as the basis for validating Markdown syntax. The markdownlint Visual Studio Code extension includes a library of rules to encourage standards and consistency for Markdown files. See this markdownlist readme file for a description of the rules we start with.

The pipeline includes a markdownlint.json file that includes custom rules and turns off rules we don’t want to use. (We turn off MD009, MD012, MD014, MD026, MD028, MD030, MD039, MD027, MD038, MD026, MD024, MD036, MD040, and MD045.) Each repo includes a markdownlint_custom.json file for turning off rules within that repo.

TIP

For editing in Visual Studio Code, an Adobe Markdown extension pack is in its final stages. For now, we recommend that you use the markdownlint extension.

This extension does not include our current set of rules, but it’s still helpful. We’re working on an Extensions Pack for Adobe that will include these rules.

Matt’s wiki

Matt’s Jenkins documentation

Resolve Git conflicts

A Git conflict occurs when an edit in your branch is in conflict with an edit in the master branch that occurred since you created your branch.

The most common Git conflict occurs when two people try to make changes to the same section of content within an article.

For a detailed description of how Git conflicts can occur, see the Merge Conflicts section.

  1. When you submit a pull request, check to see if there’s a conflict between your branch and the master.

    Git conflict image

  2. Click Resolve Conflicts.

    Git conflict editing image

    In this example, one person changed “AEM rendered” to “staged” and another person added links in the same line. Git doesn’t know which change to pick, so it flags the conflict and makes you decide.

  3. Edit the section or sections with conflicts. Remember to remove the extra lines that are added.

  4. Click Mark as resolved.

    Git conflict editing image

  5. Click Commit merged.

Clicking the “Commit merged” option commits the changes you made to your pull request. You can then go on to merge the pull request, assuming of course that the Jenkins validation check passes. If not, well, keep reading.

NOTE

What if “Resolve Conflicts” is dimmed?

If “Resolve Conflicts” is dimmed, it means there is a Git conflict that cannot be resolved in the editing view. For example, if one person deletes, moves, or renames files that another person edits, that’s a more gnarly problem. You usually need to make the same file changes in the branch and then commit the changes to that branch. Or, contact a member of the SSE team or your local Git expert to help you resolve it.

If you’re willing to blow away the changes to resolve this conflict, select the branch in GitHub Desktop, choose Repository > Open and enter git reset -hard master and then git push --force (it’s the equivalent of deleting/re-creating the branch).

On this page