Notes for DLang maintainers

Tue Feb 28 08:45:31 PST 2017

On Tuesday, 28 February 2017 at 15:49:56 UTC, Andrei Alexandrescu 
wrote:
> There can be any amount of discussion about this, to no 
> conclusive results, and any argument may be responded with "I 
> don't buy that". That's simply because, again, there's some 
> subjective factor and there is no perfect approach that proves 
> the others wrong. To wit, I have stated my argument several 
> times in public and private but somehow it did not count.

Apologies if I have forgotten about any important arguments from 
past discussions; however, I can't recall any substantial ones 
that would settle this argument.

> Also, obviously the Internet can be used to find support for 
> anything, and with that caveat allow me:
>
> * "Why does every serious Github repo I do pull requests for 
> want me to squash my commits into a single commit?" 
> http://softwareengineering.stackexchange.com/questions/263164/why-squash-git-commits-for-pull-requests

The top answer advocates not squashing the commits when it 
doesn't make sense to.

> * "I’ve been contributing to more projects in which it is 
> expected that I should submit a pull request that contains a 
> single commit." 
> http://ndlib.github.io/practices/one-commit-per-pull-request/

This article was brought up here before, with a similar debate.

> * "Squashing your branch's changes into one commit is "good 
> form" and helps the person merging your request to see 
> everything that is going on." 
> https://github.com/projecthydra/hydra-head/blob/master/CONTRIBUTING.md

Only suggests considering whether squashing is appropriate. Links 
to the previous article.

> * "But one thing occasionally bothers me, and that's pull 
> requests that come loaded with several temporary commits. I 
> often find myself asking contributors to squash those into a 
> single descriptive commit." 
> http://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit

Mentions that the steps are for dealing with "temporary commits". 
Does not advocate one style over the other.

Perhaps there is some misunderstanding on what the point of 
disagreement is?

- Splitting changes across multiple pull requests is a point 
orthogonal to this one. I do wish we would adopt a workflow where 
larger pull requests are acceptable as long as the changes are 
properly divided into commits, as I believe it would be overall 
more productive; however, this is not what this thread is about.

- Squashing temporary commits is always good. We are both in 
agreement here.

- What we seem to disagree on is whether commits should be 
squashed in other cases. You argue that if a pull request 
contains enough changes that they could be split across several 
commits, they should be split across several pull requests. I am 
not contesting this argument (at least in this discussion). 
However, you also seem to say that pull requests containing 
enough changes that they could be split across several commits 
should be squashed into a single commit before merging, which is 
what I can't comprehend.

To reiterate, squashing commits that do not need to be squashed 
destroys information (commit messages and separation of changes) 
and makes bisecting, blaming and generally examining git history 
more difficult. Squashing discourages splitting changes into 
granular commits (even smaller than would make sense for a PR), 
and documenting each in part. Writing detailed commit messages is 
really important - not only does it provide additional context to 
people not familiar with the code base in question, it also 
forces the author to review their justification for the changes 
and consider alternative solutions.

What does squashing achieve, on the practical front?

> Vladimir, I am gathering that this makes you unhappy and are 
> close to getting ultimative about this.

What I'm unhappy about is that waste so much time arguing about 
things that seem to have an obvious correct answer, and when I 
ask for rationales for your decisions, I get huge replies about 
politics and what Facebook does and how these discussions don't 
scale and zero practical arguments to support your point. This is 
a systematic problem and has happened several times before.

Where are the practical arguments?

Closest thing is link number 2. Quoting:

> For pull requests, a single commit is easier to inspect, 
> critique, and discuss. By creating a single commit, I am saying 
> “This is a logical unit of work” for the project. I can explain 
> what and why these changes are made - developer documentation 
> if you will. At a future date, for other contributors, it is 
> easier to get a context for a small change in one file if that 
> change tracks to a larger unit of work.

Exactly the same arguments apply to each commit in a commit 
series which should not be squashed.

Where is the rationale for squashing self-contained commits with 
well-written commit messages over not doing so?

> * Any organization, be it for profit (company) or not 
> (university, oss project) has certain rules in place. In all 
> likelihood not all participants would choose the exact same 
> rules if they could, yet they choose to walk (factually or 
> virtually) in there every day and contribute to the 
> organization. A simple way to look at things would be, would 
> you quit a job or start a protracted argument with the CEO if 
> the coding guidelines contained "please squash your github 
> commits"?

If a company's internal guidelines contain rules written by the 
CEO, that most workers disagree with, and which seem to lead to 
the opposite of productivity, it would certainly be a big red 
flag.

> * The leader of an organization (in this case me) cannot afford 
> the time to justify and debate every single minor decision they 
> make. No organization works that way. I am under enormous 
> pressure to bring money in the Foundation, organize DConf, 
> mentor students, write articles, contribute code, all while 
> keeping things running.

This is why people delegate, right? As you're aware, both Martin 
and I are in favor of squashing conservatively.

> * You seem to frame things as an arbitrary imposition made by 
> an oppressive leadership. Think of it - ever since we have 
> worked together (your first post is dated 2007-01-06!), is this 
> the pattern by which matters have been conducted? Do you think 
> it would be a fair characterization of Walter and my philosophy 
> and values?

Let's not pretend that there have been zero decisions made 
seemingly in opposite to the community's consensus before. And, 
reminder: I did start the page 
http://wiki.dlang.org/Language_issues :)

> The short of it is we simply cannot work this way, as a simple 
> matter of my own human limitations; I can't spend hours in the 
> forum justifying every little thing, especially those that ten 
> people do in eleven ways. I mean I _literally_ can't: I don't 
> have the time because I am spending it making the D language 
> more successful. Which I hope you'll help me with, too. To 
> scale, we need to focus on the real problems and abandon 
> debating the small things again and again.

I understand, but it's not either-or. I think delegation and 
trust in the community are both viable alternatives... but, more 
importantly, for the past few instances the discussions would 
have been a lot shorter if we'd stick to the practical arguments 
that matter.

To try to cut a long thread short, you wrote:

> Please reach to squash commits as the default, unless there is 
> a special case.

> with exceptions that need to be justified.

I just think that "multiple self-contained commits which are too 
granular to split into multiple PRs" should be an implied special 
case that should not be justified. This is all.