I just wanted to say a few words about how I've been developing for GNU Radio using Github as my primary place to work. I use github because it seems to make things easier to track, its stable, and provides a nice interface for me and anyone else to work with. It also provides the benefit of being very easy to set up and doesn't depend on any of us GNU Radio guys to be in the critical path. You are free to branch, work on github, and then do what you want with the branch.
Hopefully, at some point you'll have done something great and want to see it go back into GNU Radio. At that time, you can contact me and/or Johnathan Corgan and ask us to merge it into the main GNU Radio tree. We'll check it over, play with it, ask questions, maybe ask for some rewrites. If all looks well, we'll merge it with one of the main GNU Radio trees (i.e., maint, master, or next) and you're done!
This post includes the largely unannotated description of how to work with git and github to do what you need to get a branch in and out of GNU Radio. I won't spend time going into what's happening, why, and what else you might be able to do with git. If you want that, you can go read the git documents out there already. I've found gitready and the Pro Git Book to be good resources for these questions.
1. Clone the GNU Radio repository
From the gnuradio.org Redmine resource, you get access to the GNU Radio git source with:
git clone git://gnuradio.org/gnuradio.git
That gives you access to the main branches. These are maint, master, and next.
2. Set up an account with Github
Just got to the website and follow the instructions to set up an account. It's really easy. For simplicity sake, we'll say you got an account called "watson," and you named your project "gnuradio." This gives you a git repository called:
git@github.com:watson/gnuradio.git
3. Add your Github repository as a remote
You want to set up a remote access to this branch from your GNU Radio clone you've just made:
git remote add watson git@github.com:watson/gnuradio.git
Notice that we've used the "git@github..." URL. This is secure, read/write accessible form of your repository, and it will be called "watson" now. When you type git remote, you should now two items, "origin" and "remote." The "origin" is the GNU Radio repository you made when you did the clone.
You probably want to do a git fetch watson just to do it. Right now, though, your remote should be empty, so it won't actually do anything. That'll be an important command later, though.
4. Push to the new repo
You now want to populate your repository. I like to have a copy of the "master" branch on my remote repo. I don't know why this one exactly, but it gives me a good base to work with. It also makes sure you're doing things correctly at this point.
git checkout master
git push watson master
The first command just makes sure you are in the "master" branch. The second command actually sends the local branch to the remote repository you've given; in this case, "watson." If you look on Github, you should be able to do look at the "Switch Branches" drop-down box and see that you indeed have a "master" branch there.
I like to try to keep this guy up to date. So when you go and pull a new "master" down from GNU Radio, you should then issue the git push watson master command to update the remote.
5. Make a working branch
The important stuff comes when you actually want to create something with GNU Radio. You're going to make a branch to work in and keep it stored on Github. Before creating a branch, you need to decide which branch you are going to branch off of. As I've mentioned before, GNU Radio keeps 3 main branches going: maint, master, and next. I don't want to go too deeply into the differences here, and you can read up on Git to try to understand these branches better (we follow the normal Git workflow conventions here; see man gitworkflows). Basically, maint is bug fixes from the last version; master is the main development branch for stuff that adds functionality but doesn't make too many changes to the API or behavior; next is where all of the crazy stuff happens (you'll find major changes like UHD taking place in next). So think a bit about what you are attempting to do and decide which branch best fits your needs. You can always branch off someone elses branch if they've been doing something you require.
Ok, you've got a branch picked out. Let's just say you're working from "master" to make things easy. Start by making sure you are in master, then create a new branch and check it out.
git checkout master
git branch newwork
git checkout newwork
Now make some changes. If you're not overly familiar with Git, it's not too hard. If you are familiar with CVS of Subversion, it might actually be a bit harder to reorient yourself to how it works. Mainly at this point, we care that Git is a distributed management system. What that means for us now is that you can work on your own machine as much as you like and never actually affect anything on the server until you want to. So when we do a "commit," we're only working locally. It's only when we actually "push" code that the server gets update. I tell you, this is a great feature when working on a plane or train and you aren't connected to the Internet. You can keep small, self-contained commits going and then push them when the time is right. You can also do other Git magic, but I'll let you discover that for yourself.
To commit, use the git commit command:
git commit [options]
Look into Git to see what I mean by options. If you want to commit everything all at once, you can just use:
git commit -a
But there are other ways of going about it.
So you've done your work and want to push it to Github. You do this because maybe you just want to keep your work stored someplace safe. Or maybe you're going to share it with someone else, or, like me, you work on a number of different machines and use it to keep your development branches synced. Whatever, I don't care. You just know that you are ready to push. It's easy:
git push watson newwork
Bang! Done. You don't even have to name it "newwork," use whatever you want.
You can then commit, push, pull, and all that other fun stuff. I'll let you play from here.
6. Merge it into GNU Radio
You probably won't be doing this step. We have some quality control for what ends up on the GNU Radio git branches. There are a handful of people who are able to push directly to these branches, though. If you are really active with the project and really want to participate that closely, talk to us. But keep in mind that we're acting as gatekeepers here to ensure a level of quality and stability to the code base. We like to make sure the code doesn't affect the build, introduce large bugs or major problems (we all introduce bugs, this is to try and minimize it), doesn't duplicate efforts, and is a good fit to be included in the code base. Again, at this point, we will work together to get your code in and placed correctly.
But let's say you can talk directly to the GNU Radio git server. What would you do? Or in most cases, what do we do with your branch? It's a merge and push, really. You've finished "newwork" and want it moved into "master," so you send me an email explaining this:
"Hi Tom,
Great work on the project! You're really amazing! [ok, you don't need to include that part].
I've just completed "newwork" that does "what newwork does." I branched it off "master" and you can find it here:
git://github.com/watson/gnuradio.git
Please merge this with "master."
Thanks!
Me"
I'll set up to track your remote branch, check out the logs, see what you've done, and then make the decision to either merge it or maybe ask you to make some corrections or edits. But let's just say that it's perfect and ready to be merged. Here are the basic steps, as long as nothing weird happened:
git remote add watson git://github.com/watson/gnuradio.git
git fetch watson
git branch --track newwork watson/newwork
[maybe do some work myself here]
git checkout master
git merge newwork
git push origin master
We're done. The "master" branch contains your changes. You can now get rid of your branch if you want:
git branch -d newwork
git push watson :newwork
I included that last bit because I find it to be one of Git's most confusing syntaxes. Seriously? A colon is a remote delete? We couldn't have done something more expressive? Well, whatever. That's what it is.
That's it!
So now go and have fun with GNU Radio! And if you want to track my work, I keep a repo on Github at:
git://github.com/trondeau/gnuradio.git