enforce conventional commit for PR titles

[scarf005]

what is conventional commit?

https://www.conventionalcommits.org/en/v1.0.0/

why is it needed?

1. improves consistency as now #### Summary can be removed.
2. improves readability as category is available from PR title.
3. easier changelog tool integration as it only needs to parse structured PR title.
4. enforcing changelog categories can be automated using Semantic PR.

how would the new PR title look like?

there's two options:

use conventional commit as types, use changelog categories as scope

fix: firing gun causes segfault
feat(content): new mutation category 'Mouse'
feat(interface, port): option to disable auto pickup
perf(port): migrate to std::optional

• strictly follows conventional commit
• these categories are obsoleted over native conventional commit types:

From	To
Bugfixes	fix
Performance	perf
Infrastructure	refactor
Build	build

• may be awkward to type feat(feature) <- rename categories to more descriptive one?

use changelog categories as type

fix: firing gun causes segfault
content: new mutation category 'Mouse'
ui(port): option to disable auto pickup
perf(port): migrate to std::optional

• port: port changes from other forks

[Coolthulhu]

I'd rather have titles be just "Adding x to y", as before, but auto-tagged as "content" because the SUMMARY line in the PR itself contains this tag.
Is it doable?

[scarf005]

it's doable. DDA has workflow file to validate and label it using regex. to continue from discord:

As for enforcing, I'd rather have it be read from some other part of the PR, not the title. The bot could add it as tags.
More readable than having tags as text
Also, more searchable

'readable and searchable' could be solved in conventional commits as well since they can be labelled by bots. and i disagree that using DDA tools to parse previous summaries is a good idea, because homebrew tools introduce maintainance cost. if we ported DDA workflows, we now need to maintain additional 3 workflow files to validate and label PRs:

DDA summary validator (16 lines)

name: PR Validator
on:
  pull_request:
    branches:
      - master
    types: [opened, edited, synchronize]
jobs:
  validate:
    name: Validate PR
    runs-on: ubuntu-latest
    steps:
      - name: "Validate SUMMARY"
        uses: CleverRaven/pr-validator@master
        with:
          description-regex: '(\n|^)#### Summary\s+`{0,3}(SUMMARY:\s+)?(None|((Features|Content|Interface|Mods|Balance|Bugfixes|Performance|Infrastructure|Build|I18N) +".+"))`{0,3}\s*(\n|$)'
          description-regex-flags: "i"

DDA summary labeler (13 lines)

# .github/workflows/summary-labeler.yml
name: Summary Labeler

on:
  - pull_request_target

jobs:
  uses:
    name: labeler
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: fuxingloh/multi-labeler@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          config-path: ".github/summary-labels.yml"

DDA summary pr regex (42 lines)

# .github/summary-labels.yml
version: v1

labels:
  - label: "<Enhancement / Feature>"
    matcher:
      body: "(\\s|^)#### Summary\\s*Features +\".+\"\\s*(\n|$)"

  - label: "Info / User Interface"
    matcher:
      body: "(\\s|^)#### Summary\\s*Interface +\".+\"\\s*(\n|$)"

  - label: "Mods"
    matcher:
      body: "(\\s|^)#### Summary\\s*Mods +\".+\"\\s*(\n|$)"

  - label: "Game: Balance"
    matcher:
      body: "(\\s|^)#### Summary\\s*Balance +\".+\"\\s*(\n|$)"

  - label: "<Bugfix>"
    matcher:
      body: "(\\s|^)#### Summary\\s*Bugfixes +\".+\"\\s*(\n|$)"

  - label: "<Bugfix>"
    matcher:
      body: ".*((C|c)lose(s|d)?|(F|f)ix(es|ed)?|(R|r)esolve(s|d)?):? #([1-9][0-9]{3,6})(\\s*|$)"

  - label: "Code: Performance"
    matcher:
      body: "(\\s|^)#### Summary\\s*Performance +\".+\"\\s*(\n|$)"

  - label: "Code: Infrastructure / Style / Static Analysis"
    matcher:
      body: "(\\s|^)#### Summary\\s*Infrastructure +\".+\"\\s*(\n|$)"

  - label: "Code: Build"
    matcher:
      body: "(\\s|^)#### Summary\\s*Build +\".+\"\\s*(\n|$)"

  - label: "Translation"
    matcher:
      body: "(\\s|^)#### Summary\\s*I18N +\".+\"\\s*(\n|$)"

wheras existing toolings can be used for conventional commits. in fact, there's abdundance of tools for it.

validation is much simpler:
(using semantic-prs)

# .github/semantic.yml
titleOnly: true
types: [
  feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, # existing types
  content, ui, balance, mods, i18n # BN specific types
]
scopes: port

labelling is also very straightforward:
(using auto-badge)

# .github/badge.yml
types:
  feat: Features
  content: Content
  ui: Interface
  mods: Mods
  balance: Balance
  i18n: I18n
  fix: Bugfixes
  perf: Performance
  refactor: Infrastructure
  build: Build

as we get to use more complex documentations this will be more prominent.

[scarf005]

fixed by #3536