New Relic Repolinter Improvements

[prototypicalpro]

Hello from New Relic's Open Source and Developer Advocacy team! We've implemented a number of large changes to Repolinter in our fork, but before we create a pull request we want to elaborate on the growth opportunities we needed to see addressed.

Our changes mainly concern how Repolinter is applied in our organization: instead of having each project maintainer apply Repolinter to their project, we sent out pull requests to install repolinter-action onto their repository. Before we did any of this, however, we wanted to ensure that we could be as transparent as possible regarding what the tools we were installing did and what rules were being enforced. This led to three primary categories of modifications to Repolinter:

• Rulesets should be understandable and editable without too much prior knowledge.
• Repolinter's output should drive clarity: providing a what, why, and next steps.
• Repolinter should support the centralization of policies/rulesets.

Ruleset Clarity

In applying Repolinter to other repositories, we found that the rulesets switched from being treated like a configuration to being treated like a policy: the ruleset is no longer something made by a developer; instead, the ruleset is synthesized from Open Source guidelines by a member of the Open Source team. Because of this change, we found we could no longer expect that the person creating a Repolinter ruleset was familiar with JavaScript linting tooling, creating a barrier between the policy creator and the policy itself.

To address this issue, the ruleset configuration structure was transitioned into a more readable but less compact format, as shown below. This format includes a JSON schema which enables IDEs such as VSCode to autocomplete fields.

{
    "axioms": {},
    "rules": {
      "all": {
        "license-file-exists:file-existence": ["error", {"files": ["LICENSE*", "COPYING*"], "nocase": true}]
      }
    }
}
// becomes
{
  "$schema": "https://raw.githubusercontent.com/todogroup/repolinter/master/rulesets/schema.json",
  "version": 2,
  "axioms": {},
  "rules": {
    "license-file-exists": {
      "level": "error",
      "rule": {
        "type": "file-existence",
        "options": {
          "files": ["LICENSE*", "COPYING*"],
          "nocase": true
        }
      }
    }
  }
}

Support for creating a configuration in YAML was also added. This particularly helped with long strings:

license-file-exists:
  level: error
  rule:
    type: file-existence
    options:
      files:
      - LICENSE*
      - COPYING*
      - >-
        some really long pattern
      nocase: true

This change only applies to rulesets with version: 2 specified.

Output Clarity

We found that the output Repolinter provided clearly indicated a problem, but didn't elaborate on any solutions or the policy in question. This worked well when a project maintainer installed/maintained Repolinter on their own project, but led to confusion when the tool was applied externally. To increase the clarity of Repolinter's output for a project maintainer unfamiliar with the tool we implemented the following features:

• The ability to add "fixes", which would automatically be applied or suggested if a rule failed.
• Adding configuration fields to supply policy-related information, displayed with the output of a rule.
• A markdown formatter for Repolinter's output.

The cumulation of these changes translated an the output of a rule from this:

✖ license-file-exists: Did not find a file matching the specified patterns (LICENSE*)

to look like this:

### ❌ `license-file-exists`

New Relic requires that all open source projects have an associated license contained within the project. This license must be permissive (e.g. non-viral or copyleft), and we recommend Apache 2.0 for most use cases. Did not find a file matching the specified patterns (`LICENSE*`).

🔨 **Suggested Fix**:

- `LICENSE`: Create file with text from https://www.apache.org/licenses/LICENSE-2.0.txt.

Organization Compatibility

To help maintain policy consistency across our organization, we chose to centralize the Repolinter rulesets in our newrelic/.github repository. This change ended up being mostly implemented in repolinter-action, but to facilitate local development a --rulesetUrl option was added to fetch a ruleset from a remote host.

Other Changes

We ended up refactoring a good part of the codebase while in the process of adding functionality. A full list of changes can be found under the changelog.

Thanks for your hard work building this tool so far, and we hope these changes will contribute to Repolinter as a whole.

[caniszczyk]

@prototypicalpro this is AWESOME, we would love to take the contributions in

[caniszczyk]

@prototypicalpro also would you be interested in becoming a maintainer on the project?

[prototypicalpro]

Thanks, I appreciate it! I've opened the PR for this issue: #174.

I am definitely interested in becoming a maintainer for Repolinter if that's something you're looking for. Perhaps we can discuss further over slack after this PR is resolved?

[caniszczyk]

These were merged in, thanks @prototypicalpro

Can you also update and fix the API references in a PR? e.g., https://newrelic-forks.github.io/repolinter/#api-reference

[prototypicalpro]

@caniszczyk Sure! There is an existing GitHub Pages site already deployed: https://todogroup.github.io/repolinter/. Is it OK if I replace it with the autogenerated documentation?

[caniszczyk]

That works for me

…

On Wed, Sep 30, 2020 at 4:43 PM Noah Koontz ***@***.***> wrote: There is an existing GitHub Pages site already deployed: https://todogroup.github.io/repolinter/. Is it OK if I replace it with the autogenerated documentation? — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#173 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAPSILMTZDHRNPXFIEF5VTSIORAVANCNFSM4QNTE4KA> .

-- Cheers, Chris Aniszczyk http://aniszczyk.org +1 512 961 6719