When you've completed your feature¶
n.b. For any protoDUNE DAQ software developer, gaining a working knowledge of the git repository system is an investment in time that will well be worth it; while some git commands are provided below, see this site for a good starting point for how git works, this one for a description of the "git flow" enhancement to git (designed to make git easier to work with), as well as the appendix at the bottom of this page, focused on describing features of git you'll need to know in order to follow these instructions
As contributions to lbne-raw-data and lbne-artdaq from different groups intensifies, it becomes increasingly important that the changes each group commits to the "develop" branch of the packages' git repositories not impede the development process of other groups when they pull these changes. With that in mind, the following are a set of recommended procedures which, when followed during the commit of a group-specific feature to the "develop" branch, should help achieve this goal:
1) When working on a feature, perform the work on a feature branch, NOT on the "develop" or "master" branches
The "master" branch is meant for official releases, and is rarely touched- in fact, on 35ton, constant development occurred through the lifetime of the run, and there never WAS one single official release. The "develop" branch, used by all groups working on protoDUNE DAQ software, should only be committed to when a given feature is complete. In the development process within a specific group, however, smaller commits may be appropriate from the perspective of the incremental development of a feature. So, during the development process within a group, please use a feature branch for these frequent commits. If your alterations involve changes both to lbne-raw-data and lbne-artdaq, please give the feature branch you work on the same name in both repositories.
To create a feature branch from the head of a repository, assuming you've already run "source setupLBNEARTDAQ" and cd'd into the package you're planning to modify, do the following:
git flow feature start <name of feature> git flow feature publish <name of feature>
2) Make sure commits to the feature branch are pushed to the central repository
This is for two reasons. First, if you accidentally delete or otherwise destructively interfere with your local changes, you'll have a safe backup in the form of the central repo's feature branch. Second, when you complete a feature and wish to add it to the develop branch, the "best practices" below require that this feature be in the central repo and not just in a local area.
To accomplish this, you can do the following:
git status # To see which files you've modified git add <file1> <file2> … # Files to add to a commit git commit -m "<string providing your initials and a brief summary of the changes the commit introduces>" git push origin feature/<name of feature>
3) When you're ready to add a completed feature to the "develop" branch, make sure the code in the develop branch will continue to build correctly and that the feature continues to do what you expect it to
One common pitfall when a group merges its feature branch into the develop branch occurs when the group has been working in a directory that was created weeks or even months ago with a now-outdated version of lbne-raw-data and/or lbne-artdaq. It's possible that a feature which worked when developed off of the old version of the package won't work when added to the latest version (i.e., the head of the develop branch). To check whether this is the case, once your feature branch has been pushed to the central repository, check out, install and build the latest version of lbne-artdaq as described in Installing and building the lbne-artdaq code. Then, assuming that BASE_DIR is the base directory where you've performed the installation, cd into the source code of the package you've modified:
cd <BASE_DIR>/srcs/<PACKAGENAME> # PACKAGENAME would be lbne-raw-data or lbne-artdaq
and now check out your branch, and merge any new code from the develop branch into it:
git fetch origin git checkout feature/<name of feature> git merge develop
If you've got feature branches for both packages, you'd do this for both of them, of course. Make sure that if there are any conflicts that you handle them, and then make sure the system builds:
cd <BASE_DIR> source setupLBNEARTDAQ mrb b
It's also recommended that you check that the system runs correctly and that your changes have their intended effect. If this is the case, then commit the changes to the feature branch and push them to the central repository; once you've done this, you can close out the feature branch and merge it into develop:
git flow feature finish <name of feature>
Notes on "git" specific to this page¶
Gaining write access to the central repo¶
When a git repo is set up, it can be set up in such a fashion that users have read-only access to it -- meaning, in this context, that they can commit in their local repo, but can't push the changes to the central repo. You can see this if you look at the name given to the central repo:
git remote show origin
if the central repo name is given as
http://cdcvs.fnal.gov/projects/<packagename>, then you have read-only access. To gain write-access, do the following:
git remote rm origin git remote add origin ssh://p-<packagename>@cdcvs.fnal.gov/cvs/projects/<packagename>
Note that this will only work if you're on the developer list for a package.
If you encounter a merge conflict¶
When you try merging one branch into another, it's possible that a copy of the same file has been edited on each branch separately. In this case, git will often not be intelligent enough to determine how to merge the two files. Say, for example, that I have a file called "foo.txt" in a project, whose contents look like this on the head of the develop branch:
This is the foo.txt on the develop branch
but like this on the head of a feature branch called "feature/otherfoo":
And this is the foo.txt on the feature/otherfoo branch
Then, if I'm on feature/otherfoo, and I run
git merge develop, then I get the following:
Auto-merging foo.txt CONFLICT (add/add): Merge conflict in foo.txt Automatic merge failed; fix conflicts and then commit the result.
and if I now look at foo.txt, I see the contents of the file have changed to the following:
<<<<<<< HEAD And this is the foo.txt on the feature/otherfoo branch ======= This is the foo.txt on the develop branch >>>>>>> develop
essentially, git decides not to pick one version of the line over the other, and instead presents them both, delineated with
">>>>>>>". In a real repository, if you see a merge conflict you'll want to search for these distinctive delineators to find the locations where there were merge conflicts in your file(s). Once you've edited them to your satisfaction, you'll want to perform a commit of the merge-corrected files; in the example we're using, say I edited foo.txt to look like the following:
foo.txt was actually pretty similar on both the develop and the feature/otherfoo branches
then I would want to commit this file via:
git add foo.txt ; git commit -m "<Some string describing how I fixed the merge conflict"
Of course, before committing anything to the "develop" branch, you want to communicate with any other people/groups who made edits which conflict with your own!