Procedure for merging branches from old regional_workflow repository to ufs srweather app

The first section of this document outlines the step-by-step procedure that will be applied to the ufs-srweather-app repository to complete the merger of the regional_workflow repository. The second section outlines the procedure that users will have to complete in order to bring existing work from their fork of regional_workflow into their fork of ufs-srweather-app.

Procedure for authoritative repository

This procedure was performed on Thursday, September 8; full details on the timeline can be found in the public announcement document.

git clone git@github.com:ufs-community/ufs-srweather-app
git clone git@github.com:ufs-community/regional_workflow
cd regional_workflow
git filter-repo --path ecflow/ --invert-paths
git filter-repo --path fix/ --invert-paths
git filter-repo --path gdas.v15.0.0/ --invert-paths
git filter-repo --path gempak/ --invert-paths
git filter-repo --path gfs.v15.0.0/ --invert-paths
git filter-repo --path gfs_workflow.v15.0.0/ --invert-paths
git filter-repo --path global_shared.v15.0.0/ --invert-paths
git filter-repo --path sorc/ --invert-paths
git filter-repo --path util/ --invert-paths

These “git filter-repo” commands are not part of the merge; this is an opportunistic cleanup operation being performed as described in the public notice document

cd ../ufs-srweather-app/
git remote add rw ../regional_workflow
git fetch rw
git merge rw/develop --allow-unrelated-histories
git push

This constitutes the completion of the command-line procedure. The regional_workflow develop branch (with its git history and directory structure) are now merged into the ufs-srweather-app develop branch, and the former is now obsolete and frozen. The remainder of the changes necessary to account for the new directory structure were applied via PR: https://github.com/ufs-community/ufs-srweather-app/pull/343

Procedure for user forks

Users who have existing work in a branch of their regional_workflow fork need not despair: this procedure details the process of moving existing work from a branch in a user fork of regional_workflow into the same user’s fork of ufs-srweather-app. These instructions are much the same that will be performed on the main repository, but with extra steps to ensure no data is lost, as well as resolving merge conflicts.

Important steps prior to starting

1. If you do not have any existing work from branches in your regional_workflow fork, you do not need to take any special action. Simply update your ufs-srweather-app fork from the main repository as you would normally.

2. If your changes in regional_workflow are simple, it will likely be quicker just to re-apply them in a new ufs-srweather-app branch

3. Prior to this procedure you should update the develop branch of your ufs-srweather-app fork from the main repository; you should be able to do this through the GitHub web interface by visiting your fork's URL (https://github.com/your_fork_name/ufs-srweather-app).

   • 

4. Do not be intimidated by the number of commands. Most of these are either for general repository cleanup, or safety to ensure that you do not lose any work.

5. If you suspect something has gone wrong in this process, contact kavulich@ucar.edu. This procedure will not affect your original regional_workflow fork on GitHub, so it should always be possible to recover lost work if something goes wrong.

Procedure

export fork_name=your_github_username

• tcsh shell users should stop using tcsh. But if that's not an option, substitute the appropriate "setenv" command here to set these environment variables.
• Users should insert their own github username here

git clone git@github.com:${fork_name}/ufs-srweather-app
git clone git@github.com:${fork_name}/regional_workflow

• This is the procedure for cloning with SSH, can be cloned through HTTPS as well if you haven't set that up

mkdir backups/
tar -cf backups/ufs-srweather-app.tar ufs-srweather-app
tar -cf backups/regional_workflow.tar regional_workflow

• Ideally it should be impossible to mess things up too badly, but just in case, it's always a good idea to clone backups of your repositories when outside of your comfort zone.

cd regional_workflow
git filter-repo --path ecflow/ --invert-paths
git filter-repo --path fix/ --invert-paths
git filter-repo --path gdas.v15.0.0/ --invert-paths
git filter-repo --path gempak/ --invert-paths
git filter-repo --path gfs.v15.0.0/ --invert-paths
git filter-repo --path gfs_workflow.v15.0.0/ --invert-paths
git filter-repo --path global_shared.v15.0.0/ --invert-paths
git filter-repo --path sorc/ --invert-paths
git filter-repo --path util/ --invert-paths

• These “git filter-repo” commands are not part of the merge; this is an opportunistic cleanup operation being performed as described in the public notice document
• "git-filter-repo" is a fairly easy-to-install tool (https://github.com/newren/git-filter-repo), but see the README in that repository to ensure you are on a platform that meets the requirements

cd ../ufs-srweather-app/
git remote add rw ../regional_workflow
git fetch rw
export branch_to_merge=branchname

• Replace "branchname" with the branch you wish to bring over from your regional_workflow fork.

git checkout $branch_to_merge

• If this git checkout command fails, you likely have an identical named branch in your ufs-srweather-app fork already. The easiest way to get around this is to rename the branch in your regional_workflow fork, and start this process over again.

git rebase -i 30adef2

• This is the most "dangerous" step, as the rebase command always comes with a chance of losing data. The git rebase command involves taking commits from the branch you are currently on, and applying them onto the "source" commit (in this case, 30adef2). This command should bring up a text editor with a list of commits from your working branch, which will be applied in sequence. After saving and quitting, the rebase procedure will start, and with each applied commit, you may have to resolve merge conflicts. If anything looks incorrect (for example, too many or not enough commits are listed compared to what you expected from this branch), contact kavulich@ucar.edu for further guidance.
• For reference, 30adef2 is the commit in ufs-srweather-app right after the merge. You can replace this with "develop" if you like, but this may result in more complicated merge conflicts.
• As mentioned above, you will likely get merge conflicts if you have changed any of the following files:
  • .github/CODEOWNERS
  • .github/ISSUE_TEMPLATE/bug_report.md
  • .github/ISSUE_TEMPLATE/feature_request.md
  • .github/PULL_REQUEST_TEMPLATE
  • LICENSE.md
  • README.md
• More information on conflicts available in Public notice: merger of regional_workflow and ufs-srweather-app repositories

git push -u origin $branch_to_merge

• You may be prompted by git to use the --set-upstream; if this happens use the suggested git push command printed on the screen.

Your fork’s branch is now up-to-date with the main, combined ufs-srweather-app repository. If you have development in additional branches that you also need to bring over, simply re-run all the commands starting from the line export branch_to_merge=branchname

Acknowledgements

This document was authored by Michael Kavulich (kavulich@ucar.edu); contact him with any questions. Special thanks to Daniel Abdi for his testing and comments on the user fork procedure, and Christina Holt, Venita Hagerty, and Mark Potts for their work and feedback in migrating automated testing to the new repository.