Post by Joseph HerlantPost by Willy TarreauThus I *tend* to think that fixing these changelogs would not
significantly help ut could add a bit of difficulty over time,
and I'd prefer to leave them as-is, at least for the git part.
Probably that the older parts are no more relevant by now so
I'm fine with any option.
Yes, that's often the problem. Some people fix this issue by adding
the commit sha (long or short) at the beginning or end of the line
(which is automatically detected if you're in markdown on github and
transformed to a link if you want to be fancy! :) ). But I see your
point.
Initially I didn't want to "pollute" the changelog with commit IDs,
in order to maintain a smooth transition. But we could probably
prepend an abbreviated ID in front of each message now.
Post by Joseph HerlantPost by Willy TarreauHowever this outlines the importance of being extra careful
in the subject line of our commit messages and to adjust this
part when applying the patch if needed, which I used not to
do too often unless the description was unclear or misleading.
Maybe we should add a point in the CONTRIBUTING file about the
importance of caring about this point.
There are some mention about being careful about typo in the section 5
about the documentation
OK, like most contributors I must confess I don't read it every day ;-)
Post by Joseph Herlantbut it may be worth having a git hook that
would warn about typos when creating a commit maybe?
Maybe. But once it's a commit it's often too late, as most devs will
not run commit --amend just to fix some typos. In fact sometimes you
think "it's temporary, I'll fix this later" then you forget, and that's
fair. I think the check should be a bit like linux's checkpatch which
works quite well for a number of things : we'd encourage contributors
to run it on their patch series before submitting. We could also run
it when applying (or as a hook to "git am"). I'm seeing some value in
this, it just deserves a bit more thinking not to be annoying, as the
most important thing is that we don't discourage contributions by
being too much into processes (hence why I'm fine with occasionally
fixing patches that I apply).
Post by Joseph HerlantPost by Willy TarreauJust thinking about something, how did you figure all these
typos ? By reading everything, or aided by some automated tool
or maybe a mix of all of this ? I'm asking in case we could try
to improve our tools to spot mistakes before and after patch
submissions.
I saw some typos while reading the documentation so I ran misspell
(https://github.com/client9/misspell) on it. There are some false
positives sometimes with it so you have to re-read it carefully but it
generally does a good job at detecting common typos.
Great! I didn't know about it at all, thanks for the info.
Post by Joseph HerlantI generally use this one as it's a commonly used tool in the golang
world when you care about linters but it's applicable in most text
files.
Right now misspell detects over 300 issues over the entire repo,
Not bad ;-)
Post by Joseph Herlantnot 100% fixable, but that was the point of
https://github.com/haproxy/haproxy/pull/1 which I'll be breaking down
in several patches when I got more time in the days to come.
Yes, your work is very welcome, and it's the perfect moment for this, as
we're getting closer to the release so the changes should progressively
slow down in importance, hence there's more room for less intrusive
cleanups.
Thank you!
Willy