Nim: [git] rename git branch `devel` to `master` and `master` to `stable`

[timotheecour]

was discussed briefly in https://forum.nim-lang.org/t/4091#25452 and @araq seemed in favor so putting it here so it doesn't get forgotten

copying from that post:

In vast majority of git projects, master means branch with latest developments, but in Nim, master points to latest dot release IIUC, and devel is the branch with latest developments.

[EDIT] changes in code + docs would also need to happen right after

non exhaustive list:

• [ ] let commit = getConfigVar(d.conf, "git.commit", "master")
• [ ] exec("git checkout -f master")
• [ ] docker pull nimlang/nim:devel
• [ ] git checkout devel

SCRATCH BELOW

thanks @dm1try for correcting me on this point
Here's an example where this non-standard convention gets in the way when deleting a feature branch after it was merged (via a PR) to devel, git complains (with a warning) because it expects HEAD to point to master, not a custom name like devel if we were using master instead of devel, we wouldn't have this warning

git checkout devel
git pull --ff-only
git branch -d pr_fix_7492_doAssert_bad_stacktrace_simple
warning: deleting branch 'pr_fix_7492_doAssert_bad_stacktrace_simple' that has been merged to
         'refs/remotes/rdev/pr_fix_7492_doAssert_bad_stacktrace_simple', but not yet merged to HEAD.
Deleted branch pr_fix_7492_doAssert_bad_stacktrace_simple (was 11e70d109).

[Araq]

Please give me a detailed list of git instructions and I'll do it. Maybe I'll test first with a dummy repo and ensure not every outstanding PR gets broken.

[dom96]

AFAIK we can just do the following:

• Create branch off master called stable.
• merge devel into master.
  
  
  
  • Do so periodically while PRs for devel exist
  
  
  • Tell people to make PRs on top of master
  
  
  • at some point decline PRs on top of devel
  
  

[timotheecour]

I suggest doing it in 2 steps spaced by ~1 month insead of 1 step due to fact that master already has a different meaning, and the fact that code (and docs) relies on these hardcoded names:

• step 1 (could happen now): rename branch master to stable and immediately delete branch master
• fix doc and code refs: code should now only mention stable and devel
• wait for 1 month, fixing any issues as they occur
• step 2: rename devel to master, immdediately delete branch devel, and make sure git clone now points to master
• fix doc and code refs: code should now only mention stable and master

And definitely we can try how that works out in a separate NimExperimental that is a full copy of Nim repo (with all branches), and experiment this change there

[dm1try]

i'm just lurking here but..
the first part is true:

In vast majority of git projects, master means branch with latest developments

at least in open-source projects on Ruby(in private projects, it usually depends on the team and deploy strategy)

the second part is not true:

git complains (with a warning) because it expects HEAD to point to master, not a custom name like devel

this complaint should be in the git warning then :) I mean the complaint in the message has nothing with "HEAD to point to master". the same message will be received when master will be a default branch and the next PR will be merged with squashing.

see, (was 11e70d109) in the warning, this commit was provided in PR
but it was squashed and merged as d07d148, that's all the story

BTW, HEAD is just a ref on the commit that usually points on the tip of the current branch(with an exception for "detached" head) so git changes this ref each time git checkout command is used(in your example, HEAD points to the tip of local devel branch)

[timotheecour]

@dm1try thanks for your correction, edited my post

[dom96]

step 1 (could happen now): rename branch master to stable and immediately delete branch master

Why delete it immediately?

[timotheecour]

so that mis-uses of users will fail fast instead of succeed and cause more errors down the line, both for users and maintainers (eg PR rebased on wrong branch etc, giant merges), eg:

# on branch devel
git pull --ff-only
Your configuration specifies to merge with the ref 'refs/heads/devel'
from the remote, but no such ref was fetched.

git checkout pr_experiment

git pull --rebase origin devel
fatal: Couldn't find remote ref devel

git pull origin devel
fatal: Couldn't find remote ref devel

then all user has to do is: why does my operation fail? look on github and see branches and see the new branches

This'll be also be made obvious by showing in BOLD in top of README.md for some time some notes relating to this change with link to this issue and instructions to follow for them to update their PR's:

# on branch devel
git branch --set-upstream-to=origin/master
Branch 'devel' set up to track remote branch 'master' from 'origin'.

so for @Araq could be simply:

git clone https://github.com/nim-lang/Nim
cd Nim
git checkout master
git checkout -b stable
git push --set-upstream origin stable

then, quickly got to https://github.com/nim-lang/Nim/branches

this was for my fork, need to adapt names and branch names and do this instead:

• delete branch master
• change default branch name to devel

as a result, there will only be these official branch names:

• stable, devel (no more master)

that should be it for step1 I mentioned above.

then after a month, redo this for transition devel => master