[BUG] tutorial-notebooks branch change?

[tloredo]

This may be more of a question than a bug report. But perhaps my problem is a symptom of a bug/error.

I tried today to refresh my DP0 tutorial-notebooks directory:

git reset --hard origin/main
git pull

git pull led to a conflict and launched an editor for a merge message (which I quit). git status reported:

On branch prod
Your branch is ahead of 'origin/prod' by 26 commits.
...

I don't recall ever switching to the prod branch. When I switched back to main, the reset and pull went ahead without a problem.

So two questions:

• Was I supposed to be in the prod branch?
• If not, might there have been a problem in a recent update that switched me (and maybe others) to prod?

My workflow with tutorials is to copy a tutorial notebook to a directory outside of tutorial-notebooks, specifically to avoid conflicts. So I think it's unlikely I did anything to create a conflict. But maybe I did!

[frossie]

Hi so yes, the RSP maintains automatically the prod branch of the notebooks and does its best to keep it up to date. However there are some situations where git decides there's a conflict and fails to do the update. If you have been doing your significant work in your own copy and you don't care about our version, you can just follow Option 3 in these instructions to get a fresh copy:

https://dp0-1.lsst.io/data-access-analysis-tools/index-nb-intro.html?highlight=git%20reset#what-to-do-if-dp0-1-tutorial-notebooks-do-not-automatically-update

By the way we have noted this way of keeping the tutorial notebooks up to date is confusing, and we're working on ways to improve it.

[frossie]

I'm sorry I misread your question. You're right, the instructions are wrong and it should be asking you to reset the prod branch. We'll get those fixed.

[MelissaGraham]

Thanks for bringing this up, @tloredo!! I fixed the "Troubleshooting Tip" for "What to do if DP0.1 tutorial notebooks do not automatically update" to recommend git reset --hard origin/prod.

[MelissaGraham]

And @tloredo let us know if that fully solves the problem for you, and then if so we will close this issue.

[tloredo]

So just to clarify before closing: Should I be using the prod branch to follow tutorials? I've checked out main to fix this; should I now checkout prod and do the reset for that branch, and work from there from now on?

I'll probably just hose this repo and get a fresh copy, but I'd just like to know for sure what branch we should be using. It seems unusual to me for users not to be using main (or a tagged release on main). That's the public-facing branch when someone visits a repo on GitHub. But I'm not an expert on Git workflows for large projects.

[MelissaGraham]

The RSP maintains the prod (production) branch in all users' tutorial-notebooks/ directory, so yes, that is the one users should restore to when they encounter issues.

I'll provide a bit more background info in case it's helpful: most of the time, prod and main are the same. But at other times, when Rubin staff are working on many branches of the repository and updating the notebooks, we merge these branches into main first, to effectively collect all the updates, and then do a single pull request from main to prod once we are ready to "release" new versions of the notebooks and force updates for all users.

@frossie do you think it would help users if we made the prod branch the default view (if possible) when people go to the webpage for the repository?

[tloredo]

I just started teaching a Bayesian data analysis class this week, and our first lab, today, was an introduction to Git and GitHub. I showed them that the standard way to clone a repo is to visit its page and click on the "Code" button to get the clone link. Doing that for the DP0 notebooks tutorial and cloning gives you a repo that's in the main branch. I believe even if you select the prod branch on GitHub, the clone link provided there will produce a repo in main. I think I'd have to do a git clone -b prod ... to make the new clone's HEAD point to the prod branch.

I see that you can change the default displayed branch: Changing the default branch - GitHub Docs. But it's not obvious to me that that would also change the cloning behavior.

I think the simplest/minimal thing to do is just to make it clear and prominent somewhere that users should be using the prod branch (and are put there by default by the RSP), e.g., in the README and DP0 docs that point to the notebooks repo.

[MelissaGraham]

Thanks @tloredo.

I moved this statement to the top of the readme: The prod branch will appear in IDF RSP users' home directories.

And I added more detail under the first table in the readme: Branches main and prod will usually match, except for short periods of time when updates from multiple development branches are being collected in main before "releasing" updated notebooks in a single PR to prod. The prod branch appears automatically in IDF RSP users' home directories. Any user who obtains this repository withgit clonecan switch frommaintoprodusinggit checkout -b prod` to ensure they are using the "released" versions.

It's fine if people use the main branch, since almost all of the time, main and prod are the same.

[tloredo]

Thanks, everyone, for addressing this. I think it's almost closed. I'm just not sure this is right:

git clone can switch from main to prod using git checkout -b prod to ensure they are using the "released" versions.

I believe git checkout -b NAME is for creating a new branch called NAME (git checkout prod would switch to the prod branch). Maybe you meant git clone -b prod, which would clone the whole repo but then switch to the prod branch.

[MelissaGraham]

Whoops! Removed the -b, thanks for noticing.

[tloredo]

Great, looks like we can close....

[frossie]

For the record, happy to make the default branch prod on GIthub. It was meant to be "out of the way" for the people chosing to develop on main, but since we are generally moving towards people making their own copies it doesn't matter. Thanks for the discussion.