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 >> >>
