[Improvement][Style] add autolink to issues in PR title and commit msg

[advancedxy]

Code of Conduct

• I agree to follow this project's Code of Conduct

Search before asking

• I have searched in the issues and found no similar issues.

What would you like to be improved?

It's common and considered best practice to be able to click links to corresponding issues/PRs/tickets in the commit msg. To achieve this features, Github's autolinked references and links¹ are used.

For example, Spark uses this feature to autolink Jiras.

Since Uniffle are using Github Issues to track issues/request/improvements, etc. The issue is effective the same as the Jira ticket.

I'd like to propose an suggestion to improve the code context experience: add autolink to issues in PR title and commit msg.

How should we improve?

1. Let's decide which form to include autolinks:
   • [#xxx], the simple form, cf9afab
     
   • [ISSUE #xxx] prefixed with the ISSUE
2. Enforce the pr title check. Every PR should have an issue linked.
   There's an exception rule for this: PR title prefixed with [Minor]/[MINOR] can be excused for this enforcement check.

Are you willing to submit PR?

• Yes I am willing to submit a PR!

Footnotes

1. https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls ↩

[advancedxy]

@kaijchen @zuston @jerqi @felixcheung WDYT?

[zuston]

Can we use the apache style like [UNIFFLE-120][Test] Fix msg ? And the uniffle-120 could be linked to github issue by https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources

[kaijchen]

UNIFFLE-120 may be confusing, because it's usually a Jira id.
Currently I would not recommend Jira because the self registration is limited. We wish to make new contributors easier to join the project.
For how to configure the autolink, see https://cwiki.apache.org/confluence/display/INFRA/Git+-+.asf.yaml+features

[advancedxy]

Can we use the apache style like [UNIFFLE-120][Test] Fix msg ? And the uniffle-120 could be linked to github issue by https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-autolinks-to-reference-external-resources

No. The asf doesn't expose the configurations to external resource except JIRA which is already been closed for public registration.

I'd like to use [ISSUE-#xxx], but it seems Github doesn't recognize that. You have to use [ISSUE #XXX] or [Uniffle #xxx] or just [#xxx]

[kaijchen]

I would suggest omit issue id in the title, and just add it in the PR description.

### Why this change needed?

Fix #123

The PR title could be [module][type] description.

Modules:
Info of who (module owner) should review this pr.

• coordinator
• server
• client
• operator
• *: all
• etc

Types:
Implies the urgency, the review time required, and whether should be backported to release branches.

• feature: (new feature for the user, not a new feature for build script)
• fix: (bug fix for the user, not a fix to a build script)
• docs: (changes to the documentation)
• style: (formatting, missing semi colons, etc; no production code change)
• refactor: (refactoring production code, eg. renaming a variable)
• test: (adding missing tests, refactoring tests; no production code change)
• chore: (updating grunt tasks etc; no production code change)

[advancedxy]

I would suggest omit issue id in the title, and just add it in the PR description.

### Why this change needed?

Fix #123

The point to add issue id in the title is that we can links to issues and commits in Github's ecosystem. In most cases, only title is displayed for commits.

Another benefit to include issue id in PR title(included in commit title automatically) is the commit is also linked to the issue.
See #545 for example

[kaijchen]

The point to add issue id in the title is that we can links to issues and commits in Github's ecosystem. In most cases, only title is displayed for commits.

My point is, by just looking at the issue id, you don't get any information.
When looking at commit history, you got interested by the scope and type of the change first.
Then you start to looking for why it's needed, and find the related issue.

Just click the 3 dots, you could see it the description.

[advancedxy]

The point to add issue id in the title is that we can links to issues and commits in Github's ecosystem. In most cases, only title is displayed for commits.

My point is, by just looking at the issue id, you don't get any information.

No, the auto-linked issues is clickable. You can jump to the issue page by simply looking at the title just as you can jump to the pr page.

[jerqi]

It's ok for me.

[advancedxy]

@kaijchen @zuston does this demonstrate the benefits of autolinks?

[advancedxy]

kaijchen zuston jerqi felixcheung WDYT?

also cc @xianjingfeng which was pointed to a wrong one.

[zuston]

It's OK for me, thanks for your effort. @advancedxy

[xianjingfeng]

kaijchen zuston jerqi felixcheung WDYT?

also cc @xianjingfeng which was pointed to a wrong one.

It's OK for me.

[kaijchen]

Seems the following format is preferred now?

[#123] feat: add xxx feature
[#124] fix: exception in xxx 

[advancedxy]

Seems the following format is preferred now?

[#123] feat: add xxx feature
[#124] fix: exception in xxx 

It's preferred to use conventional commits. But I don't think all the committers are ready for this. Let's keep it as a personal preference for a while? If everyone agrees with conventional commits, we can also enforces this.

[advancedxy]

Also FYI, I add an exception rule:

[kaijchen]

How about combine issue ID and semantic commit message ?

[<issue>] <type>(<scope>): <subject>

For example:

[#123] feat(operator): support xxx
[MINOR] refactor: fix typo in variable name
[#233] fix: check null before xxx
[MINOR] chore(deps): bump grpc to xxx

[kaijchen]

Hi everyone, I've edited existing open PR titles (to show examples to new PR). How do you think?