Integrate gitStream with Javadoc

Javadoc Examples:

Review Javadoc Changes
Review Java Input Parameters for Javadoc Changes
Review Javadoc for Large Changes
Enforce Javadoc Requirements for New Classes

Review Javadoc Changes

Unblock PRs that only change Javadoc content.

Review Javadoc Changes

Configuration Description

Conditions (all must be true):

The PR only contains changes to Javadoc content.

Automation Actions:

Assign the org/tech-writersteam for optional review.
Apply a green 📓 Javadoc Only label
Approve the PR

Review Javadoc Changes

# -*- mode: yaml -*-
manifest:
  version: 1.0
automations:
  # Assign PRs that only affect JavaDocs to the technical writing team and add docs label
  review_javadoc:
    if:
      - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | every }}
      - {{ source.diff.files | matchDiffLines(regex=r/\b(public|protected|private|static|final|synchronized)?\s+\w+\s+\w+\s*\(([^)]*)\)\s*\{/) | nope }}
    run:
      - action: add-label@v1
        args:
            label: "📓 Javadoc Only"
            color: {{ colors.green }}
      - action: add-reviewers@v1
        args:
          reviewers: [org/tech-writers]
      - action: approve@v1

colors:
  green: '0e8a16'

Download this example as a CM file.

Review Java Input Parameters for Javadoc Changes

If a PR modifies the input parameters for a Java method, but not the associated Javadocs, notify reviewers to check for Javadoc updates.

Review Javadoc Input Parameters

Configuration Description

Conditions (all must be true):

The PR changes one or more input parameters in Java methods.
- Note: This may not trigger for methods with annotations, methods that throw exceptions, multi-line method definitions, and other non-standard use cases.
The PR lacks changes to ‘@param’ declarations.

Automation Actions:

Post a comment warning the user to review the method’s Javadoc to identify necessary updates.

Review Javadoc

# -*- mode: yaml -*-
manifest:
  version: 1.0
automations:
  review_javadoc_input_parameters: 
    if:  
        - {{ source.diff.files | matchDiffLines(regex=r/\*\s@param/) | nope }}
        - {{ source.diff.files | matchDiffLines(regex=r/\b(public|protected|private|static|final|synchronized)?\s+\w+\s+\w+\s*\(([^)]*)\)\s*\{/) | some }}
    run:
      - action: add-comment@v1
        args: 
            comment: | 
              This PR modifies method input parameters, but is missing Javadoc changes. Please check to ensure no Javadoc changes are necessary.

Download this example as a CM file.

Review Javadoc for Large Changes

Require more extensive reviews for large Java changes that lack Javadoc updates.

Review JavaDoc for Large Changes

Configuration Description

Conditions (all must be true):

The PR changes more than 25% of a Java class.
The PR lacks Javadoc changes.

Automation Actions:

Post a comment asking the author to review all relevant Javadoc to identify necessary updates.
Require a review from the my-organization/tech-writers team.
Apply a yellow ⚠️ Missing Javadoc Label

Review Javadoc for Large Changes

# -*- mode: yaml -*-

manifest:
  version: 1.0

automations:
  #Require more extensive reviews for large Java changes that lack Javadoc updates.
  review_javadoc_large:
    if:
      - {{ changes.ratio > 25}}
      - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
    run: 
      - action: add-label@v1
        args:
          label: "⚠️ Missing Javadoc"
          color: {{ colors.yellow }}
      - action: add-comment@v1
        args: 
          comment: | 
              This PR makes major changes to Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.
      - action: add-reviewers@v1
        args:
          reviewers: [fourth-organization/tech-writers]

changes:
  # Sum all the lines added/edited in the PR
  additions: {{ branch.diff.files_metadata | map(attr='additions') | sum }}
  # Sum all the line removed in the PR
  deletions: {{ branch.diff.files_metadata | map(attr='deletions') | sum }}
  # Calculate the ratio of new code
  ratio: {{ (changes.additions / (changes.additions + changes.deletions)) * 100 | round(2) }}

colors:
  yellow: 'fbca04'

Download this example as a CM file.

Enforce Javadoc Requirements for New Classes

Automatically request changes when someone creates a new Java class that lacks Javadoc content.

Enforce Javadoc Requirements for New Classes

Configuration Description

Conditions (all must be true):

The PR creates a new Java class.
The PR lacks Javadoc content.

Automation Actions:

Apply a ⚠️ Missing Javadoc label.
Request changes, and post a comment explaining that Javadoc is required

Review Javadoc Requirements for New Classes

manifest:
  version: 1.0

automations:
  review_new_class_javadoc:
    # Triggered for new Java files that lack Javadoc content.
    if:
      - {{ is.java and is.new }}
      - {{ source.diff.files | matchDiffLines(regex=r/\/*\*([\s\S]*?)\//) | nope }}
    run: 
      - action: add-label@v1
        args:
          label: "⚠️ Missing Javadoc"
          color: {{ colors.yellow }}
      - action: request-changes@v1
        args:
          comment: | 
              This PR creates new Java classes, but is missing updates to Javadoc. Please double check for any necessary Javadoc updates.

is:
    java: {{ files | extensions | match(term='java') | every }}
    new: {{ source.diff.files | map(attr='original_file') | match(regex=r/^$/) | some }}

colors:
  yellow: 'fbca04'

Download this example as a CM file.

Special thanks to Boemo W Mmopelwa for providing these examples.