proposal: v2 Improve and simplify config format

[peaceiris]

Discussed in #445

^{Originally posted by Andre601 June 16, 2021}
I feel like the config is kind of bloated in some sections and could receive a improvement.

For example do I see no reason for having a lock option when the only goal for it is to have lock and unlock as options. This could just be an option for the action field and result in close + lock or open + unlock.

Another thing that could also be something to improve is the comment option.
This one could be changed to something like this:

comment: |-
  Hello,
  {{ content }}
  This is an automated comment created by a [GitHub Action](https://github.com/peaceiris/actions-label-commenter).
  Responding to or mentioning it has no effect.

The {{ content }} placeholder would then be replaced with whatever you defined in the corresponding body section of a label.

Discussed in #487 (comment)

More generic placeholders for specific values

Right now do I need to use {{ issue.user.login }}, {{ pull_request.user.login }} or {{ discussion.user.login }} to achieve the same thing for issues, PRs and discussions respectively, which is getting the username of the person that created the issue, PR and/or discussion.

This is somewhat annoying to have and I would like to propose some more generic/common placeholders to use, which would use different keys depending on the type.

• {{ author }} - Name of who created the Issue, PR or Discussion.
• {{ labeler }} - Name of who labeled the Issue, PR or Discussion.
• {{ id }} - The id of the Issue, PR or Discussion. (Maybe? Can't think of a good use-case here)

[github-actions]

Hi, there.

Thank you @peaceiris for suggesting this.

---

This is an automated comment created by the peaceiris/actions-label-commenter. Responding to the bot or mentioning it won't have any effect.

Log | Bot Usage

[github-actions]

Hi, there.

Thank you for suggesting documentation improvement.

---

This is an automated comment created by the peaceiris/actions-label-commenter. Responding to the bot or mentioning it won't have any effect.

Log | Bot Usage

[Andre601]

I have suggestions for 2 possible ideas on how to restructure the file handling, which both have benefits but also disadvantages.

1) Split types up into separate files

Perhaps it could be worth it to split up issues, PRs and discussions into separate files under a label-commenter folder (i.e. .github/label-commenter/issue.yml for issue-related comments).

Benefits

• Gets rid of the issue, pr and discussion sections used for each label.

Downsides

• 3 times the files you have to maintain both as action or user of it.
• No easy way to apply header or footer (common parts) to it. Would probs require a 4th file for it.

2) Separate MD file per label

Maybe giving each label a own Markdown file could be the way to go.
The settings could then be applied through YAML frontmatter, allowing pretty much the same level of control you currently have + some more.

Files would be (similar to the previous idea) be located in a label-commenter folder inside the .github one to keep it clean.

Example file named spam.md:

---
allowed: # List of types this action should reply to
- issue
- pull_request
- discussion

# Used to "close", "open", "lock" or "unlock"
action: 'lock'
reason: 'spam' # Used when "lock" is set as action

# Settings to exclude Header/Footer
exclude_header: false
exclude_footer: false
---
## 🔒 LOCKED
This {{ type }} has been **locked** <!-- Maybe a new "{{ type }}" placeholder returning the type? (Issue, Pull request or Discussion) -->
Reason: Spam.

A dedicated _header.md and _footer.md could be used to apply header and footer to the comments.

Benefits

• Much easier file-setup for the end-user (Doesn't need to make sure YAML formatting is correct with exception of frontmatter part)
• Better control about actions.
• Easy extendable. GitHub added a new thing the action could be used on? Just add it to the allowed list and save.

Downsides

• Not all label formats/names may be supported (i.e. emojis). Is : f.e. supported in file names?
  • Would probably require some work-arounds (label sanitization?) to make it work with more special labels.
• Requires more advanced file handling (1 file per label is a lot)
• YAML Frontmatter handling. Not sure how hard or easy this would be.

---

If I had to choose would I honestly go with the second option.

[peaceiris]

Those are interesting. But we should consider using the YAML anchor/alias at first.

labels:
  - name: locked (spam)
    labeled:
      issue:
        body: &locked_spam_body |
          This issue has been **LOCKED** because of spam!

          Please do not spam messages on this project. You may get blocked from this repository for doing so.
        action: close
        locking: lock
        lock_reason: spam
      pr:
        body: *locked_spam_body
        action: close
        locking: lock
        lock_reason: spam
      discussion:
        body: *locked_spam_body
        locking: lock
        lock_reason: spam

[peaceiris]

When we check a rendered body with GitHub Flavored Markdown, the yq and grip are useful.

• mikefarah/yq: yq is a portable command-line YAML processor
• joeyespo/grip: Preview GitHub README.md files locally before committing them.

Rendered YAML body

yq e '.labels[10].labeled.pr.body' .github/label-commenter-config.yml

[The documentation label] was added. Thank you for suggesting documentation improvement.

When you add a new section, do not forget to update the Table of Contents.

[The documentation label]: https://github.com/peaceiris/actions-label-commenter/issues?q=label%3Adocumentation

Rendered Markdonw body

yq e '.labels[10].labeled.pr.body' .github/label-commenter-config.yml | grip -

[peaceiris]

Splitting file looks interesting but I won't do that. I am sure that the current single YAML file approach is enough simple in the viewpoint of usability and maintainability.

[Andre601]

Fair enough. Just thought it could be an interesting approach but there are obvious drawbacks and issues with it.

[peaceiris]

Maybe we can get another better approach in the future, so I will keep that in mind. Thank you!

[Andre601]

Looking back at this after a relatively long time, I still have a good feeling about using separate markdown files for the different label actions, tho now I think about a slightly different approach.

You would still have own markdown files, but the main YAML configuration would now be used to define them.

Imagine the following files:

• .github/label-commenter/issue-enhancement.md

  {{ header }}
  
  Thank you @{{ author }} for suggesting an improvement to this project!
  
  {{ footer }}

• .github/label-commenter/pr-enhancement.md

  {{ header }}
  
  Thank you @{{ author }} for proposing an improvement through a pull request!
  
  {{ footer }}

• .github/label-commenter-config.yml

  comment:
    header: Hi, there.
    footer: "\
      ---\n\n
      > This is an automated comment created by a GitHub Action.\n
      > Replying or mentioning the bot has no effect."
  
  labels:
    - name: 'enhancement'
      labeled:
        issue:
          template: '.github/label-commenter/issue-enhancement.md'
        pr:
          template: '.github/label-commenter/pr-enhancement.md'

The main configuration, including actions such as opening or closing an issue/PR would remain in the main configuration file, but content to comment would be out-sourced to those markdown files to use.

Placeholders such as {{ header }} and {{ footer }} would exist that would get replaced with their respective values from the config alongside any other supported placeholders...

Maybe, if that is wanted by others could a {{ config.<path.to.option> }} placeholder be considered to allow others to define custom values inside the main configuration?

This would keep the main configuration a lot cleaner because even with that YAML anchor/alias thing is it not the best to look at.

All this is up to you of course.