Project

General

Profile

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 "<<<<<<<<", "=======", and ">>>>>>>". 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!