Hi,
Just keep in mind that the purpose of these tempates is to help to
growth the community of the project and having new committers, so it can
help new comer to learn how the ASF is working, even if reading the
community guide lines should be the starter.
regards,
François
Le 26/10/2025 à 12:02, Alexandre Dutra a écrit :
Hi all,
I disagree with the idea that commit messages should be devoid of
informative content. On the contrary, detailed commit messages are
crucial for understanding the purpose of changes, especially large
ones, when browsing the commit log. I'm not advocating for excessively
long messages, but a reasonable amount of text can be highly
beneficial. I personally always provide detailed information in my
commits, a practice even endorsed by the author of Git himself [1].
However, this deviates from our main discussion regarding PR templates.
The argument that we should adopt long-ish templates because projects
X, Y, or Z do so is unconvincing. We cannot assume the majority is
always correct, and we don't know if the templates are causing
frustration and deterring first-time contributors from opening PRs.
Furthermore, our existing contribution guidelines, **which
contributors are expected to read**, already contain extensive
instructions for PR contributors [2]:
The Pull Request description should provide the background (rationale) of the
change and describe the changes in way [sic] that someone who has no prior
knowledge can understand the rationale of the change and the change itself.
[...] Test that your changes work by adapting or adding tests. Verify the build
passes.
To me, this is more than enough. I tend to disregard checklists and
TODO lists as a reviewer, as there's no guarantee contributors have
completed them in good faith (and besides, the Definition of Done is a
subjective notion).
On the changelog topic: I agree that maintainers should update it, if
the PR author didn't, in order to accelerate the review process. This
kind of polishing can be more easily achieved when PR authors allow
edits by maintainers, as a maintainer can push a "polishing commit" to
the PR before squashing. Spring Boot does this often to enforce
formatting, naming conventions, changelog entries and other similar
chores that PR authors aren't familiar with. I think we could do the
same in Polaris.
Finally, I also prefer when the PR template is included in an HTML
comment. It greatly reduces the visual clutter when the PR description
is rendered. Two good examples of concise-ish templates using HTML
comments are: Spring Boot [3] and Quarkus [4].
To move forward on this topic, I propose a compromise: let's implement
a template, but keep it as concise as possible, linking to the Polaris
contribution guidelines. If we need to add more instructions, let's
enrich the guidelines themselves, not the PR template.
Would this approach be acceptable to everyone?
Thanks,
Alex
[1]:
https://github.com/torvalds/subsurface-for-dirk/blob/master/README.md?plain=1#L128-L157
[2]:
https://github.com/apache/polaris/blob/main/CONTRIBUTING.md#opening-a-pull-request
[3]:
https://github.com/spring-projects/spring-boot/blob/main/.github/PULL_REQUEST_TEMPLATE.md?plain=1
[4]:
https://github.com/quarkusio/quarkus/blob/main/.github/PULL_REQUEST_TEMPLATE.md?plain=1
On Sun, Oct 26, 2025 at 8:23 AM Jean-Baptiste Onofré <[email protected]> wrote:
Hi
I do agree that the commit message should be short and concise (it’s what I
said in my previous message). It should not contain anything about the
issue details or use case: that’s in the github issue.
The PR template should just reflect the contributing guideline helping the
contributor.
Several projects were very demanding when a contributor creates a PR and
they now use a lighter approach because it had an impact to contributions.
Regards
JB
Le sam. 25 oct. 2025 à 23:58, Eric Maynard <[email protected]> a
écrit :
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.
