Hi Ali, Thanks for sharing your view.
I agree that an issue or discussion should not replace a good PR description. They serve different purposes. The PR should still clearly explain the change itself, including what is being changed and any important implementation details. But issues should be the place to discuss whether a change is needed, what the scope should be, and how the work should be broken down before the implementation is already done. For example: • Opening an issue or discussion first can help avoid unnecessary PRs by aligning on scope and direction early. • An issue can also track the bigger picture across the different stages of the same work, instead of being tied to just one code change. A task may start with one PR, then later need follow-up PRs for tests, refactoring, docs, or edge cases. Sometimes it may even need a revert or be revisited later. Keeping that under one issue makes it much easier to see the full history, while each PR is usually just one step in the process. • GitHub issues are not just for users to report bugs. They are also a way for maintainers to make visible what work needs attention, so people in the community can more easily see where they can help. If all that context stays internal, external contributors will not really know what to work on, and that makes it much harder to grow the community. • In another thread we are also discussing github project management, I think this is actually one of the stronger use cases for issues. A larger effort can be opened as one parent issue and then broken down into sub-issues for separate steps, with progress tracked over time. We have mostly been opening PRs only after the code is already implemented. In that case, the discussion about whether we need the change, what the right scope is, and what exactly should be done ends up happening inside the PR itself, or offline discussion. I think that is not ideal. By that point, someone has already spent time implementing the change, so it becomes harder to step back and discuss direction openly. It also makes the PR carry too many roles at once: design discussion, scope discussion, and code review. That can make the review process heavier, and it gives less visibility to people who may want to contribute earlier but are not following every PR closely. We really cannot scale with this model going forward. For all those reasons, I am casting my own +1, and I sincerely hope we can rethink about this from a bigger picture. Sincerely, Yicong Huang [email protected] On Mar 11, 2026 at 11:56 AM -0700, Ali Risheh <[email protected]>, wrote: > -1 > Treating Issue or Discussion as documentation of a PR is not the purpose of > them. > In my point of view, Issues are the problems users encounter and open one > to explain what was the error (issue) and how to replicate it. > Discussion is a place for brainstorming and exchanging ideas. > Each PR has a dedicated PR description to include all the information and > documentation and I prefer to have everything in one place. > It is just a personal opinion. > > Best regards, > Ali > > On Tue, Mar 10, 2026 at 2:43 PM Yicong Huang <[email protected]> > wrote: > > > Hi everyone, > > > > I would like to start a vote on adopting the following contribution policy > > for Apache Texera: > > > > Proposal > > > > For pull requests that are not minor, contributors should include at least > > one related GitHub Issue or GitHub Discussion reference in the PR > > description. > > > > Examples of acceptable references include: > > > > • Closes/Fixes/Resolves #1234 > > • Related to #1234 > > • Discussion #1234 > > > > The goal is to make sure each non-minor code change is connected to its > > original problem statement, motivation, or prior discussion context. > > > > Rationale > > > > Today, many PRs do not properly fill in the “Any related issues, > > documentation, discussions?” section in the PR template, and some PRs do > > not link any issue or discussion at all. This makes review and long-term > > maintenance harder. As discussed in #4246, issue/discussion linkage > > improves traceability, preserves decision context, and helps contributors > > and reviewers understand why a change exists. It also makes it easier to > > track follow-up work, revisions, and related PRs over time. > > > > Scope / exception > > > > Minor PRs can be exempt, such as: > > > > • typo fixes > > • comment-only changes > > • very small non-functional cleanup > > > > One way to handle this is to explicitly mark such PRs as minor. > > > > What this vote is about > > > > If this vote passes, we will treat issue/discussion linkage as the > > expected policy for non-minor PRs, and we can follow up with practical > > enforcement details in the PR template and/or CI checks. If the vote does > > not pass, we will continue to treat those information as optional fields. > > > > Please vote: > > > > • +1: support adopting this policy > > • 0: no strong opinion > > • -1: do not support adopting this policy, preferably with explanation > > > > > > This vote will remain open for at least 72 hours. > > > > > > Thanks, > > Yicong Huang > > [email protected] > > > >
