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.
