Hi Dmitri Thanks for starting (re-starting :)) the discussion.
Generally speaking, a template is useful if it guides and informs the contributor. Personally, most of the time, I don't think the templates are super helpful (due to the content). If the template has to be informative for the contributors, it should not ask more than what the contributor can easily do. I think we should avoid too much constraints that can be a brake to contribution. Specifically about our current template, some thoughts: * If the PR is "linked" to an issue, there's no need to describe the changes in the PR because it should be in an issue, and so in the commit message. So, maybe we should encourage people to use/create corresponding issues. If there's no issue, then it's OK to describe quickly the PR purpose. We should phrase that better than "What changes were proposed in this pull request?". * About the test, a change should have corresponding tests if needed. Having a manual test scenario is acceptable and described in the PR. I would propose to have just a checkbox like "do you have corresponding tests", if not the user can provide a manual test case. * About the CHANGELOG, imho; it's not something we should ask the contributor, because he doesn't really know the changelog details and format needed (potentially). So, I would say it's more something that the reviewer should help with, eventually guiding the contributor in terms of changelog. As today nothing is "enforced" about the template, it's fine. If we can improve the contributor experience, it's even better :) Regards JB On Fri, Oct 24, 2025 at 4:24 PM Dmitri Bourlatchkov <[email protected]> wrote: > > Hi All, > > I'd like to (re-)open a discussion for our PR template. > > Using [2883] and other recent PRs as an example of the _description_ usage > (not code). > > * What changes were proposed in this pull request? > * Why are the changes needed? > > I do not find these sections useful. Any responsible PR author should cover > these items in every commit message anyway. Having special sections is more > of a nuisance IMHO as it require working with test in GH UI to fill them > out or delete (while the idea is already in the commit message). > > * Does this PR introduce any user-facing change? > > This is a very broad topic and probably depends a lot on specific use > cases. In principle, any code change is a user-facing change as it affects > how Polaris works. > > * How was this patch tested? > > Again, responsible PR authors should include CI tests as appropriate. > Reviewers should hold contributors accountable for that. Having to fill > this section out is overhead, IMHO. > > * CHANGELOG.md > > This section header is not informative as it stands. > > In any case as discussed before [2] reviewers have a duty to requests > changelog changes if they would be meaningful, but got missed. While PR > authors are encouraged to add CHANGELOG entries proactively, I do not think > having a forced sub-section for that in each PR is worth the extra > complications in the PR submission workflow. > > I propose: > > * Remove all forced section headers from the PR template (we could keep > them in comments). Basically use an empty default template. > > * Add changelog notes to the Contributing Guidelines on the site [1] > > [1] https://polaris.apache.org/community/contributing-guidelines/ > [2] https://lists.apache.org/thread/c9y0f0z7nyoclvtzr12v8ryqq55dqzd5 > [2883] https://github.com/apache/polaris/pull/2883 > > WDYT? > > Thanks, > Dmitri.
