Enforce PR template compliance and require related issue/discussion reference

[Yicong-Huang]

Task Summary

Many pull requests are not following the PR template well, especially the "Any related issues, documentation, discussions?" section. In multiple PRs, there is no linked issue/discussion (e.g., #1234), which makes review and traceability harder.

Why this is a bad practice

• It weakens traceability: reviewers cannot easily connect code changes to the original problem statement or decision context.
• It slows down review: missing context forces reviewers/maintainers to ask follow-up questions and increases review cycle time.
• It hurts project hygiene: release notes, changelog curation, and future maintenance become harder without issue linkage.
• It reduces accountability: unclear ownership/scope makes regressions and follow-up fixes harder to track.

Priority

P1 – High

Task Type

• Code Implementation
• Documentation
• Refactor / Cleanup
• Testing / QA
• DevOps / Deployment

[carloea2]

Hi, one question, for a PR with no logical change and few changes (even 2 chars), an issue is still a good practice?

[Yicong-Huang]

those can be exempt. The best example is fix a typo or some comment. one way to do it is to declare minor on a PR directly.

[chenlica]

We have an ongoing discussion #4228 about this topic. We will conclude there first.

[Yicong-Huang]

Let’s have an informal discussion here first, and we can do an official vote if needed.

My point is simple: we should enforce an “issue first” policy. In most open source projects, the issue tracker is the system of record for proposals, bugs, and planned work (todo). The expected flow is: open an issue, discuss and align, then implement via one or more PRs. In Spark and many earlier apache projects, issue refers to JIRA. In our context, by issue I am referring to "GitHub Issue" or "GitHub Discussion" (they are parallel).

This mattered less when the project was small and centralized, and people could coordinate through face to face chats. But as the project grows and more contributors work async, that model breaks down. We need a shared, durable place for context and decisions.

Issues provide that context. A single issue can capture the motivation, alternatives, and decisions, and then link to one or multiple PRs over time: initial attempt, revisions, follow ups, even reverts. Without an issue, a PR shows up with no background. Reviewers don’t know why it exists, what options were considered, or whether there were prior attempts. If a PR gets closed and a new one appears later without linkage, all the context is lost. It also hurts contributors. Without issues, it’s hard to see what work is in flight and where the project is headed, so people duplicate effort or build something that gets rejected simply because the direction was decided elsewhere.

In the last 25 merged PRs, 15/25 had no linked issue. In the latest 25 open PRs, 18/25 have no linked issue. I tried to review some of them last week but found myself have no context at all. An example is this one, where the PR describes only dropping CI tests for Python 3.10 and 3.11 without providing any context or reasons. Another merged PR unfortunately only described the removal of the deprecated feature without providing history or reason.

By enforcing "issue first" or "issue before PR", many of those problems can be solved.

• Every PR has a clear “why” and a place to discuss alternatives.
• Reviewers can catch context quickly and avoid repeating questions across PR iterations.
• Contributors can browse issues to find work, avoid duplication, and align on direction early.
  There are extra benefits too (triage, planning, release notes), but that’s not the main point here.

I understand this adds one extra step, especially for small fixes. But for a growing project, it’s a small cost that pays back quickly in reviewer time, fewer misunderstandings, and smoother collaboration. If we want a lightweight rule: bugs, features, and behavior changes must have an issue; truly trivial changes (typos, comment fixes) can be exempt.

That is the main thing I wanted to enforce. And the enforcement of PR template + Github Action (the implementation in #4228) is just one way to enforce "issue first". I am fine if we use another method to enforce it.

[aglinxinyuan]

I’m not against this idea. My concern is about the decision-making process. If we are considering a project-wide change, especially one that affects every contributor’s workflow, it should go through a formal voting process. This is not about which approach is “correct,” which one is “better,” or what other projects are doing. When we change a practice that impacts everyone, it’s important to gather and consider everyone’s input.

I also dislike enforcing this requirement through our own GitHub Action. The implementation in #4228 feels somewhat hacky and relies on HTML parsing and regex, which can easily become outdated. If we want to ensure that PRs reference issues, reviewers can verify this, or we can consider using a well-maintained third-party action. Maintaining around 100 lines of custom code in our repository for such a simple check does not seem ideal.

[Yicong-Huang]

That's fine. we can go with a formal vote. Let's sit for a day, I want to gather other ideas (if any) before the formal vote.

We can discuss about the implementation later (and better on the PR itself). I did not search if any existing actions are available, not to mention they may not be allowed by apache. It is not worth the time for such a simple task. In fact, maintaining 100 lines of our own INFRA code IMO is better than relying on third party tools, as we can easily make it cater to our need. That's said, better PRs/tools are welcome!

[chenlica]

I support the idea of "issue first." I also support doing a discussion then a formal vote before we implement the idea.