GitHub - espressif/shared-github-dangerjs: This is a reusable GitHub Action CI DangerJS workflow for Espressif GitHub projects. (original) (raw)

Espressif Shared GitHub DangerJS

Welcome to the DangerJS Pull Request linter!

This is GitHub action that can be used across different Espressif GitHub repositories and helps make sure that contributors Pull Requests (PRs) follow a specific style.

It checks things like:

sufficient merge request descriptions
meaningful commit messages in conventional commit style
size of changes in MR
simple branch git history
source and target branch

Because DangerJS does this automatically, human reviewers can focus more on code changes and spend their time reviewing PRs more productively.

Usage in Your Project
DangerJS rules
UI output
Configuration Options
Project issues
Contributing

Usage in Your Project

To integrate DangerJS, add GitHub workflow .github/workflows/dangerjs.yml to your project with this content:

name: DangerJS Pull Request linter on: pull_request_target: types: [opened, edited, reopened, synchronize]

permissions: pull-requests: write contents: read

jobs: pull-request-style-linter: runs-on: ubuntu-latest steps: - name: Check out PR head uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.head.sha }}

- name: DangerJS pull request linter
  uses: espressif/shared-github-dangerjs@v1
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note: The permissions: block here is doing basically nothing; both values are default, and it would work the same without this block. It is recommended, though, to keep this block in the workflow file to be more explicit about workflow permissions since this action is running with the pull_request_target trigger. Feel free to remove the permissions block if a minimalist syntax suits you better.
GitHub token This token is automatically obtained from the GitHub project and its specific permissions are set in the yaml workflow file. Avoid adding unnecessarily high permissions to this token, keep it set as in the example above.

🤝 Quick Integration: If your goal is to add Shared GitHub DangerJS into your project with the default Espressif settings, then at this point you're all set!

For custom configurations, refer to the descriptions of individual rules to learn how to tweak them to your needs.

📖 Important note: The Danger action will not run in the pull request where you are adding this to your project. This is due to the workflow trigger pull_request_target; this trigger runs code in the context of the target branch (typically master/main), and at that point, the workflow file is not there yet.

It will work for all subsequent pull requests right after workflow file .github/workflows/dangerjs.yml is on the default branch of your project.

We recommend creating an independent PR just for this and not mixing it with other code changes or repository workflow file updates. That way, it can be easily merged and be ready for your contributors' PRs.

DangerJS rules

UI output

BOT comment Output Instructions format

Configuration Options

If your project has specific needs, Shared GitHub DangerJS can be configured to meet them.

Here is complete list of configurable parameters:

Parameter	CI Variable	Type	Default value
Enable rule PR Description	rule-description	str	"true" (use "false" to disable this rule)
Enable rule PR Lint Commit Messages	rule-commit-messages	str	"true" (use "false" to disable this rule)
Enable rule PR Size (changed lines)	rule-size-lines	str	"true" (use "false" to disable this rule)
Enable rule PR Source branch name	rule-source-branch	str	"true" (use "false" to disable this rule)
Enable rule PR Target branch name	rule-target-branch	str	"true" (use "false" to disable this rule)
Enable rule PR Too Many Commits	rule-max-commits	str	"true" (use "false" to disable this check)
Commit message allowed "Type"s	commit-messages-types	str	"change,ci,docs,feat,fix,refactor,remove,revert,test"
Commit message maximum length "Body" line	commit-messages-max-body-line-length	str	"100"
Commit message maximum length "Summary"	commit-messages-max-summary-length	str	"72"
Commit message minimum length "Summary"	commit-messages-min-summary-length	str	"20"
Ignore sections of PR description when counting length	description-ignore-sections	str	"related,release,breaking"
Maximum changed code lines in PR	max-size-lines	str	"1000"
Maximum commits in PR (soft limit, throw info)	max-commits-info	str	"2"
Maximum commits in PR (hard limit, throw warn)	max-commits-warn	str	"5"
Minimum length of PR description	description-min-length	str	"50"

These values can be defined in your project DangerJS Pull Request linter workflow, for example like this:

- name: DangerJS pull request linter
  uses: espressif/shared-github-dangerjs@v1
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  with:
    instructions-contributions-file: 'CONTRIBUTING.md'
    instructions-cla-link: 'https://cla-assistant.io/espressif/test'
    instructions-gitlab-mirror: 'true'
    max-commits-info: '3'
    max-commits-warn: '6'

See more config options in DangerJS rules.

Project issues

If you encounter any issues, feel free to report them in the project's issues or create Pull Request with your suggestion.

Contributing

📘 If you are interested in contributing to this project, see the project Contributing Guide.