Merge JupyterBook 1 history to allow `git pull` etc?

[matthew-brett]

I noticed that doing git merge origin/main from my slightly out of date Jupyter Book 1 era local repo, for example at commit f226ff5, I get:

$ git merge origin/main
fatal: refusing to merge unrelated histories

Surely it would be a good idea to keep the old history around for people wanting to go back to check on previous versions?

I think all that needs doing is something like git merge -s ours <the-latest-jb1-commit> --allow-unrelated-histories - but I don't know what that latest commit was. Could someone do that and push, so that git merge and git pull works as expected?

[bsipocz]

Surely it would be a good idea to keep the old history around for people wanting to go back to check on previous versions?

It is all available in the v1 branch.

[matthew-brett]

Thanks for pointing that out - but to my specific question in the issue title - would you consider a merge of that branch to main. Otherwise, anyone with a previous clone is going to get a confusing error on doing git pull.

[choldgraf]

I agree it will certainly be confusing to folks that have cloned JB locally already, and will require basically doing this:

$ git reset --hard upstream/main

and if they want to work on v1 functionality:

$ git pull upstream v1
$ git checkout v1

If there is a way to merge the two histories that is:

• Easy, without much work
• Simple, without blowing up the size of the .git history and clone actions

Then it might be worth doing. If not, then I think we could try to help people with documentation and guidance.

Either way, I think it'd help to add documentation to jupyter-book's developer section to note how people could check-out the v1 branch if they want to work on jupyter-book 1.

[matthew-brett]

Your probably saw my suggestion above:

git merge -s ours v1--allow-unrelated-histories

So - it's very little work.

If I do a git clone of the current repo, and then git checkout -b tmp origin/v1, it's instantaneous, so I infer that git clone already gets the v1 objects, and git clone will not change performance after a merge -s ours with the v1 branch. I could have worked that out from first principles, because a git clone gets references to the remote v1 commit, so must also get all the objects it needs to reconstruct the snapshot at that commit.

If you like looking at history with git log, at least for now, it's going to be a bit confusing, because you'll see the merge of the two histories. But I doubt that would concern beginners much, and it's easy for experienced developers to deal with.

[agoose77]

Personally I'm mildly in favour of not doing this if possible. I definitely see the argument that the force-push is annoying for existing developers. Conversely, that the Git history would be entirely modified between two commits in main I think would pose a minor pain point whenever people are doing git bisect and other operations that involve trawling over the history. Those kind of pain points are more of a week-to-week thing rather than a one-off with the main(v1)→main switch.

As such, I'd like to address this issue by improving our docs in line with @choldgraf's suggestion! I'm not against changing my mind on this topic, but I feel a bit reluctant to change it unless the team feel strongly that we should.

[matthew-brett]

Yes, merging the histories would have some small cost to advanced users, but the idea was to prefer those small costs to the rather larger cost to the less-advanced user, to whom fatal: refusing to merge unrelated histories would be rather confusing.

But as time goes by, obviously, the benefit to doing this becomes less.