Redmine

Introduction

Redmine is a web-based code management system containing git repositories, issues trackers, and wikis. The lab computing division keeps most of their code and documentation in the lab redmine system. Important tools for code infrastructure, data handling and job submission are all documented here.

Mu2e used to keep our major code repositories in the lab's redmine server. Now we keep them in [GitHubWorkflow|GitHub]. As of 2021, we still have several smaller repositories on redmine, and a few are likely to stay there for the forseeable future.

This page will help with using redmine, and converting redmine to github.

Transitioning between Redmine and Github

The following sections were important during the transition into our currently recommended git workflows. Hopefully they are not relevant for current work. They have been retained for now and will be deleted at a later date.

Adapting your Existing Clones to the New Workflow

Many of you have existing clones of your own github fork that were created using an older recommended github workflow. This section discusses how to bring your clone into compliance with the new recommended workflow. We cannot give an exact script to follow since everyone's local clone is likely to be different; so the following is general guidance:

1. If you have unpushed commits on your local master, see the instructions in the hints section below.
2. If you have uncommitted changes in your checked out area, commit them to a local development branch that you intend to keep.
   1. If needed: git stash; create a new development branch starting from the current head; git stash pop.
3. If the old workflow you will have have a local branch named master and a branch named remotes/origin/master. These come from the master branch of your github fork; if you still have these branches, delete them.
   1. You cannot delete the branch that is currently checked out; therefore, to delete your local master you need first to checkout a different branch.
4. You must have a branch named remotes/mu2e/master that comes from the Offline repository in the Mu2e github instance; actually the middle "mu2e" in the branch name is just an arbitrary identifier than you can choose but it would be weird to chose anything except mu2e or Mu2e.
5. If you have existing development branches that started from something other than mu2e/master, just keep them and proceed as described in the recommended workflow; if you are lucky they will merge cleanly. If not, follow the merge/rebase procedure.
6. Start all new development branches with:

 git fetch mu2e master
 git checkout -b <new development branch name>

Here are a few hints and reminders of things to watch for:

1. Use git remote -v and git branch -avv to learn what remotes you have and what branches are tracking what other branches.
2. If your local master branch has commits on it that you need to keep, then start a new development branch from the head of master. Just develop on it normally and push it to your fork when you are ready and make a pull request when you are ready for that. If you are lucky it will merge cleanly; if not follow the merge/rebase procedure. Once you have created the new development branch you can delete the local master branch.

Migrating an existing redmine clone directory to GitHub

You can repoint an existing Offline clone from redmine to GitHub as a way of making an easy transition. To follow these instructions, you must already have a GitHub account that's registered in the Mu2e Organization. The following assumes your redmine clone is in /mu2e/app/Me/MyRedmineClone/Offline, that your GitHub username is MyGitHubName, and that you are working on a branch called MyDevelopmentBranch.

1. Login to GitHub
2. Fork Mu2e/Offline in GitHub using the 'Fork' button on the top right of the Mu2e Offline repo page
3. Add GitHub as a remote to your clone

   > cd /mu2e/app/Me/MyRedmineClone/Offline

   > git remote rename origin Redmine

   > git remote add mu2e https://github.com/Mu2e/Offline

   > git remote add origin git@github.com:MyGitHubName/Offline

   These commands are very fast as no data is actually transferred. You can see your remotes with:

   > git remote -v

   Your clone is now connected to the main Mu2e github repository and your own fork in addition to the Redmine repository. Additionally, we have changed your fork to be the default remote repository (origin)

4. Push your working branch to your GitHub fork:

   > git push -u origin MyDevelopmentBranch

After this, you can continue developing in this directory according to the general GitHub workflow described below.

I have a branch on Redmine that's not on GitHub! How do I use it now?

The official Mu2e GitHub repo will usually have only the master branch (+ maybe some tagged release branches). Currently Redmine has >100 branches. If you have a Redmine branch that is not merged in to master, you will move this branch to your fork to work on it instead.

To start, you should read the development workflow and understand remotes and forks, and have a github account and a fork of the Mu2e Offline repo.

1. Create a local clone of your Offline fork. This will be identical to cloning the official Mu2e repo (if your fork is up to date), except that the default remote (called "origin") where you will push to by default will point to your fork instead of the official Mu2e version.
git clone https://github.com/Mu2e/Offline:<your user name>/Offline
2. Add Redmine as a remote to your local clone:
cd Offline git remote add redmine http://cdcvs.fnal.gov/projects/mu2eofflinesoftwaremu2eoffline/Offline.git
3. Fetch a list of the commits and branches from redmine, and check out whatever branch you need
git fetch redmine git checkout -b <branch name> redmine/<branch name>
4. Push this branch to your fork
git push origin <branch name>
5. You should now be able to see your branch on github.com/<your user name>/Offline. You can now continue working on that branch and pushing to your fork, and when it is ready you can submit a pull request to the main Mu2e repo using the developer workflow