update the instructions in the contributing guide

[keewis]

Our contributing guide is out-of-date, we usually use merge commits instead of rebasing (which would require force-pushing). This has already lead to confusion, see #4314.

Also, I noticed that in Delete your merged branch it recommends to use git branch -d <feature-branch> after updating master. That doesn't work anymore because we've switched to squash-merges.

• User visible changes (including notable bug fixes) are documented in whats-new.rst

[max-sixty]

Agree with these changes, thanks @keewis

Stepping back on the contributing doc — I admit I haven't look at it in a while — I wonder whether we can slim it down a bit, for example by linking to other docs for generic tooling — I imagine we're unlikely to have the best docs on working with GH, for example. Or referencing our PR template rather than the (now out-of-date) PR checklist.

[keewis]

ugh. It seems this is the same error as in #4130. This time I can reproduce it locally, though, so now I'm debugging.

[keewis]

re contributing docs: would it be best to leave that to the planned docs overhaul?

[max-sixty]

re contributing docs: would it be best to leave that to the planned docs overhaul?

For sure, I didn't mean to weigh down this PR

[keewis]

okay, so it seems this happens because RTD only makes shallow copies, as soon as we call git fetch --unshallow, the version detection works again.

[keewis]

phew, it seems having support set a feature flag to not do shallow clones fixed that particular issue.

[keewis]

so I guess this is ready for review and merge?

[shoyer]

Thanks @keewis! This is indeed worth updating.

[keewis]

Just so we don't forget: do we have a place where we collect ideas for the restructuring of the docs? Or should I just open a tracking issue for this and put it into the Documentation & User Engagement board?

[shoyer]

Or should I just open a tracking issue for this and put it into the Documentation & User Engagement board?

This sounds good to me!