Hi Dave, Thanks for your suggestions!
> Our guidelines should make it super easy to make contributions. This guideline is quite easy to use/understand/find because: 1) If you review PRs recently, you'll find that many contributors start following this guideline. This is the most positive feedback and persuasive proof that the rules are easy to start. 2) The rules defined in this guideline are concise and straightforward. I've added many usage examples, visual elements, and short summaries to make things clear. If you do not want to read the whole guideline, you can still write good PR titles by just reading the examples. > I think that more should be done with GitHub labels. We certainly encourage everyone to label their PRs. However, if just using labels in PRs, others can know the changes quickly from the PR list only. But if using both labels in PRs and [tag in brackets] in PR titles, others can know the changes quickly from both Terminal (git log) and the PR list, which is useful for developers. > I think that putting [Issue 12345] in the front of a title is wasteful. A trailing hash - #12345 is a clearer and GitHub understands how to link. This guideline does not encourage to include the related issue in PR titles. It suggests "Do not use GitHub keywords followed by a #<issue-number>. This information should be provided in PR descriptions or commit messages rather than in PR titles." [1] ~~~~~~~~~~~~~~~~~~~~ Moreover, many open source communities [2][3] have well-established conventions on how to write PR titles and commit messages. As our community grows faster, it’s worth taking the time to create one since a project’s long-term success rests on its maintainability. What may be a hassle at first soon becomes a habit, and eventually a source of pride and productivity for all involved. [1] https://docs.google.com/document/d/1d8Pw6ZbWk-_pCKdOmdvx9rnhPiyuxwq60_TrD68d7BA/edit#bookmark=id.m20qcl4pppik [2] Angular: https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format [3] Taichi: https://docs.taichi.graphics/lang/articles/contribution/contributor_guide#pr-naming-conventions On Fri, Mar 25, 2022 at 12:59 AM Dave Fisher <w...@apache.org> wrote: > Hi - > > I think that these guidelines are making it hard for new contributors. Our > guidelines should make it super easy to make contributions. The guidelines > are for contributions. Contributors are the community. Committers will > review contributors PRs and can gently fix mistakes for them to show them > the way. > > I think that more should be done with GitHub labels. > > I think that putting [Issue 12345] in the front of a title is wasteful. A > trailing hash - #12345 is a clearer and GitHub understands how to link. > > Whatever is changed here is the place[1] > > But we need to judge the updated page before accepting it. We should be > working on a series of commits to the docs. I can see a few things that > should be re-written. For instance [2] doesn’t have the ICLA story quite > correct. All Committers must file an ICLA while contributors can file one > it is understood that contributions made are under the AL2. Contributions > made under a different license require discussion by the project to decide > if they are acceptable. > > ATB, > Dave > > [1] https://pulsar.apache.org/en/contributing/ > [2] > https://pulsar.apache.org/en/contributing/#optionally-submit-contributor-license-agreement > > > > On Mar 24, 2022, at 12:06 AM, Lari Hotari <lhot...@apache.org> wrote: > > > > The problem with the "Pulsar PR Naming Convention" is that it can > conflict with general Git message conventions. > > > > The PR title automatically becomes the Git commit's subject line. That's > how the PR title related to the Git commit's subject line (title). > > > > In Git, the convention is to have a subject line (title) with no more > than 50 characters. When you start adding all kinds of tags in brackets in > the title, there won't be much left for the actual content. > > > > For example, GitHub's UI suggests to write commit messages that are less > than 50 characters. There's more explanation about the "Limit the subject > line to 50 characters" rule in Chris Beam's awesome "How to Write a Git > Commit Message" blog post: https://cbea.ms/git-commit/#limit-50 > > > > Do we care about the general rule that a git commit message should be > limited to 50 characters? > > > > -Lari > > > > On 2022/03/17 02:11:54 Yu wrote: > >> Hi Pulsarers, > >> > >> We submit or review PRs almost every day, we might see many vague and > >> unclear PR titles that decrease team efficiency and productivity. > >> > >> Good PR titles offer bring many benefits, such as speeding up the review > >> process and improving search efficiency. > >> > >> To solve the vague PR title issue and move *PIP 112: Generate Release > Notes > >> Automatically* [1] forward, I've created *Guideline: Pulsar PR Naming > >> Convention* [2], which explains why you need good PR titles and how you > do > >> that with various self-explanatory examples. Also, Pulsar and client > >> release notes will be generated automatically based on the rules > defined in > >> this guide. > >> > >> Do not hesitate to comment if you have any questions or concerns. > Feedback > >> before EOD 3/21 CST is highly appreciated, thanks! > >> > >> [1] > >> > https://docs.google.com/document/d/1Ul2qIChDe8QDlDwJBICq1VviYZhdk1djKJJC5wXAGsI/edit# > >> > >> [2] > >> > https://docs.google.com/document/d/1d8Pw6ZbWk-_pCKdOmdvx9rnhPiyuxwq60_TrD68d7BA/edit# > >> > >> Regards, > >> Anonymitaet > >> > >
