developer doc sends me into detached head state

[bhaller]

The doc at https://tskit.dev/tskit/docs/stable/development.html#git-workflow tells me:

Create a “topic branch” to work on. One reliable way to do it is to follow this recipe:
$ git fetch upstream
$ git checkout upstream/main
$ git checkout -b topic_branch_name

The second command sent me into "detached head state" and produced Git's usual rather alarming warning about that. I've never really understood the whole "detached head state" thing – many Git users probably don't, since I guess it's a rather unusual state of affairs? I then did the third command above and I think I got a new branch:

bhaller@glass % git checkout -b json_struct_padding
Switched to a new branch 'json_struct_padding'

I'm a little worried, though, that having been in the detached head state is going to be problematic somehow. At a minimum, perhaps the doc can mention this and reassure the user that it is fine. But maybe a set of steps can be given that doesn't send the user into this state in the first place?

[petrelharp]

Briefly: yes, this is expected, so don't worry, but I think you're right, we should recommend a workflow that doesn't make this alarming message happen. I'll update this so lines 2-3 are replaced by

git checkout -b topic_branch_name upstream/main

[benjeffery]

Interesting, I didn't think this message was alarming.

The tskit docs are about tskit, so there's a balance between having manageable content and helping everyone in every situation. I think the current docs strike that balance but if you're motivated to raise a PR for this change @bhaller I'd be happy to merge it if it isn't too much content.

[bhaller]

Interesting, I didn't think this message was alarming.

The phrase "detached head state" already sounds pretty alarming! :->

The point is that for people who are not very experienced Git users (and who thus know what "detached head state" means), it is a very cryptic message that is confusing, and yes, alarming. It sounds like something has gone wrong.

The tskit docs are about tskit, so there's a balance between having manageable content and helping everyone in every situation.

Of course. But this message about the detached state presumably occurs for every user who follows these instructions. So this is not a marginal thing; this is not about "helping everyone in every situation", this is about smoothing out the experience that every user following these instructions will have.

I think the current docs strike that balance but if you're motivated to raise a PR for this change @bhaller I'd be happy to merge it if it isn't too much content.

It sounds from @petrelharp's comment above like he sees the problem here and plans to fix it. Thanks anyway.

[hyanwong]

FWIW, I find the message "detached head state" alarming, but have learned to just ignore it. I agree with Ben Haller that new users might not know this.