I strongly disagree with the notion that every single commit message should contain information explaining the entire PR’s intent. I have scarcely seen a project or organization where that was so and my sense is that this would be unnecessarily burdensome for contributors.
I do however think the PR template could use some tuning. The fact is that it’s not often followed, and so each PR tends to describe itself in its own way which can contribute to the mental load it takes to review a string of PRs. It might be better to adjust the template and more rigorously enforce its use. The best template, after all, is one that gets used :) —EM On Sat, Oct 25, 2025 at 9:38 AM Francois Papon <[email protected]> wrote: > Hi, > > I think it's better to have a small PR template to guide users to > contribute and also to help the reviewer. > > Having some checkbox can be useful, there is an example in some ASF > projects > ( > https://github.com/apache/shiro/blob/main/.github/pull_request_template.md > ) > > Agreed with JB, the changelog should not be updated by the contributor. > > regards, > > François > > Le 25/10/2025 à 07:18, Jean-Baptiste Onofré a écrit : > > 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. >
