https://github.com/apache/commons-geometry/pull/95 Preview: https://github.com/XenoAmess/commons-geometry/blob/add_commit_message_guidelines/COMMIT_MESSAGE_GUIDELINE.md
Xeno Amess <xenoam...@gmail.com> 于2020年7月7日周二 上午12:51写道： > Hi. > I tried to write a guide line document for this thing we discussed. > Fell free to use it in any repo you want. > And also feel free to continue the discussion, > > Xeno Amess <xenoam...@gmail.com> 于2020年7月6日周一 下午7:42写道： > >> @Gilles >> > This thread already contains concrete suggestions of what to do and not >> do, as well as further reading. >> I only see what you said should not do, but not what should do, or what >> should a commit message contains. I mean something looks like a bnf, >> telling what the commit message should contain. >> >> As for the points you shown we should not do: >> >> > IMHO, a commit message should rarely (if ever) >> > * contain redundant words (such as "fix"), >> Agreed with the thought, but sometimes do not agree with you for what be >> redundant or not. >> >> > * be a plain rewording of a trivial change (rather that the purpose >> of the change), >> Not agree, I think it's better to contain both. >> >> > * make the reviewer second-guess whether the change is warranted. >> I actually didn't get what you mean for warranted... >> >> And like I said it might be better to show some good examples and bad >> examples for each point. >> >> > If you think that they should be laid out in details belongs in the >> > "contributing.md" file(s), that's great, but *you* are welcome to >> > provide a PR. >> >> I'm not requesting you make this pr now, but I'm just want you show more >> details about your opinions. >> I will try to make a formal guideline of commit log today built on what >> you point out, and you can fill the blanks, then maybe it can help us >> discuss on every point to add and delete. >> >> Gilles Sadowski <gillese...@gmail.com> 于2020年7月6日周一 下午6:24写道： >> >>> Le lun. 6 juil. 2020 à 05:52, Xeno Amess <xenoam...@gmail.com> a écrit : >>> > >>> > @Gilles >>> > > The Commons project has existed for more than 15 years, and >>> > > the history of the repositories is the best resource for the >>> > > current style. By spending a few minutes perusing through the >>> > > commit logs, a new contributor can obtain a pretty good image >>> > > of how to comment the various types of changes. >>> > That is not that easy my friend. >>> > First, the commons project has existed for more than 15 years, if every >>> > normal contributor should track every commit log, that seems too much >>> time >>> > costing. >>> > Of course I don't mean committers of that repo should not do that, I >>> mean >>> > normal contributors. >>> >>> As I've tried to convey at another occasion, the usefulness/cost >>> ratio of many small changes (i.e. things that are *not* bugs or new >>> functionality) for the reviewer can be too high. Those things are >>> ironed out by committers (i.e. people who have shown sustained >>> interest in some project). >>> >>> > Second, what I learned from commons' repos' commit history is a total >>> mess. >>> > I've seen repo who fails its own unit-tests in every commit after 3 >>> hours >>> > after its creation. >>> > I've seen repo who merge quite some ci-failed prs. >>> > I've seen repo who allow people commit directly upon that repo, no >>> need pr >>> > unless necessary. >>> > I've seen repo who do not squash commits before merge sometimes. >>> > So that is why I said, if you want good commit log, you have to >>> formally >>> > request it, and make it clear what is good commit log style in this >>> > sub-repo. >>> >>> Although unfortunate, these are small glitches when compared to >>> the whole history of the several dozens repositories managed by >>> a very small Commons team (compared to other Apache projects). >>> >>> And, in my opinion, it is not a coincidence that they appeared >>> concommittantly with the generalization of the "GitHub-way". >>> >>> > Of course a unified commit log style seems good, but commons repos >>> > are,.....not that unified, so you need time/effort to persuade other >>> > committers, >>> >>> When people have become committers, they are hopefully aware >>> of how *their* project works. >>> >>> > that is another reason why you need to make it a clear rulebook >>> > about what is good commit log style in your opinions. >>> >>> The discussion is starting to go in circles. This thread already >>> contains concrete suggestions of what to do and not do, as well >>> as further reading. >>> If you think that they should be laid out in details belongs in the >>> "contributing.md" file(s), that's great, but *you* are welcome to >>> provide a PR. >>> >>> Thanks, >>> Gilles >>> >>> > >>> > Sujit Pal <sujit....@comcast.net> 于2020年7月6日周一 上午7:12写道： >>> > >>> > > Not a committer, just an interested observer, I got on this list >>> because of >>> > > a PR I submitted to commons-math long ago, and have stayed on since. >>> > > >>> > > There is a standard for commit messages I came across recently and >>> which >>> > > our team is trying to apply to our own commit messages. Idea is to >>> make >>> > > commit messages machine parse-able with some help from humans. >>> Thought I >>> > > would share it here in case it is of interest. >>> > > https://www.conventionalcommits.org/en/v1.0.0/ >>> > > >>> > > -sujit >>> > > >>> > > On Sun, Jul 5, 2020 at 12:26 PM Xeno Amess <xenoam...@gmail.com> >>> wrote: >>> > > >>> > > > @Gilles >>> > > > If you want a good commit message you should define good first. >>> > > > And you should understand everybody is using what he think the >>> best style >>> > > > in commit logs. (at least most of the times, when they are not in >>> hurry). >>> > > > If you really want this I think you should write a guideline or >>> rule set >>> > > > for commit message style, with good examples and bad examples, >>> then pin >>> > > it >>> > > > into CONTRIBUTION.md. >>> > > > >>> > > > IMO the style you using is too short. And should contain more >>> details. >>> > > > >>> > > > for example, you said the word fix is rundantant, whitch I really >>> cannot >>> > > > agree. If you do not add a verb who will know what we do to the >>> javadoc? >>> > > > create, add，delete, fix, refine, remake,or sync? >>> > > > All the verbs are possible, and they have different meanings and >>> use >>> > > cases. >>> > > > When I use create or add I mean there does not exist some javadoc >>> for >>> > > > something before this pr. >>> > > > When I use delete I delete some javadoc in this pr. >>> > > > When I use fix I mean the original javadoc is wrong in format or >>> meaning, >>> > > > and this pr aims to fix it. >>> > > > When I use refine I mean the original javadoc is correct, or at >>> least >>> > > > correct in format, but we make it better in this pr. >>> > > > When I use remake I mean I redo this thing. usually not on javadoc >>> l but >>> > > > sometimes on functions. >>> > > > So I do not think the verb can be deleted. >>> > > > However, if you passed a ruleset or law or something about this, >>> and pin >>> > > it >>> > > > to CONTRIBUTION.md，then I will try to follow. >>> > > > >>> > > > >>> > > > >>> > > > >>> > > > Gilles Sadowski <gillese...@gmail.com> 于 2020年7月6日周一 上午2:29写道： >>> > > > >>> > > > > Hi Matt. >>> > > > > >>> > > > > Le dim. 5 juil. 2020 à 13:39, Matt Juntunen >>> > > > > <matt.juntu...@hotmail.com> a écrit : >>> > > > > > >>> > > > > > Yes, I should have modified that commit message to indicate >>> that the >>> > > > > change was warranted. >>> > > > > >>> > > > > Thanks for the good intention, but what I'm really getting at is >>> that >>> > > > > PRs for our projects should already contain a good commit message >>> > > > > (cf. advice given in the follow-up posts); suggestions, >>> discussions, >>> > > > > etc. must be directed elsewhere (ML or JIRA). >>> > > > > [In particular, having to modify the commit message is a burden >>> when >>> > > > > the change is trivial; in that case, I would rather make the >>> change and >>> > > > > discard the PR...] >>> > > > > >>> > > > > Gilles >>> > > > > >>> > > > > > -Matt >>> > > > > > ________________________________ >>> > > > > > From: Gilles Sadowski <gillese...@gmail.com> >>> > > > > > Sent: Sunday, July 5, 2020 4:00 AM >>> > > > > > To: Commons Developers List <dev@commons.apache.org> >>> > > > > > Subject: [All][Geometry] Commit log (Was: [GitHub] ...) >>> > > > > > >>> > > > > > Hello. >>> > > > > > >>> > > > > > I'd like to collect some opinions about enforcing a minimal >>> form in >>> > > > > > commit messages. >>> > > > > > My preference is that a log message is either >>> > > > > > * terse, when the commit is trivial (e.g. "Javadoc" or "Unused >>> > > > > variable"), or >>> > > > > > * detailed but factual, if the change is not obvious. >>> > > > > > >>> > > > > > IMHO, a commit message should rarely (if ever) >>> > > > > > * contain redundant words (such as "fix"), >>> > > > > > * be a plain rewording of a trivial change (rather that the >>> purpose >>> > > of >>> > > > > > the change), >>> > > > > > * make the reviewer second-guess whether the change is >>> warranted. >>> > > > > > >>> > > > > > Informal and uninformative/noisy messages might seem the new >>> normal >>> > > on >>> > > > > > GitHub but does that mean that we pass on them in our projects? >>> > > > > > >>> > > > > > Regards, >>> > > > > > Gilles >>> > > > > > >>> > > > > > Le sam. 4 juil. 2020 à 13:48, GitBox <g...@apache.org> a écrit >>> : >>> > > > > > > >>> > > > > > > >>> > > > > > > darkma773r commented on pull request #88: >>> > > > > > > URL: >>> > > > > >>> > > > >>> > > >>> https://github.com/apache/commons-geometry/pull/88#issuecomment-653756040 >>> > > > > > > >>> > > > > > > >>> > > > > > > Merged in commit 6c90e34ff11fb9fa279d9b060abf70c14ce3cd2a >>> > > > > > > >>> > > > > > > >>> > > > > > >>> > > > > > >>> --------------------------------------------------------------------- >>> > > > > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >>> > > > > > For additional commands, e-mail: dev-h...@commons.apache.org >>> > > > > > >>> > > > > >>> > > > > >>> --------------------------------------------------------------------- >>> > > > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >>> > > > > For additional commands, e-mail: dev-h...@commons.apache.org >>> > > > > >>> > > > > >>> > > > >>> > > >>> >>> --------------------------------------------------------------------- >>> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >>> For additional commands, e-mail: dev-h...@commons.apache.org >>> >>>
