How Branches Work and How to Think About Them.

In About Translations, I described one way that tech-friendly and multi-lingual non-developers can contribute to Dogecoin. That process isn’t as simple as “just translate some strings”; you have to understand a few things about git and free and open source development and GitHub first.

It’s a start though.

Mishaboar reached out to me with a couple of questions for his own Italian translation contribution. By the way, if you speak conversational Italian, please feel free to review that PR and leave comments.

One thing that isn’t obvious to new contributors, including me way back in the day, is what to change. That’s not in the sense of which code to change, but which variant of the code to change.

What are Branches Anyway?

If you’ve used Git or another distributed version control system before, you can skip this section. As always, I’m going to oversimplify a little bit to make things easier to understand, not to be 100% completely accurate.

If you haven’t used Git much before and you want to know more about it, I recommend the site Think Like (a) Git, created by a developer I am proud to have worked with and a genuinely excellent person. One of the highlights of my work week was refactoring code with him on Friday afternoons. (Collaborative software development can and should be an enjoyable experience.)

If you go to the [https://github.com/dogecoin/dogecoin](Dogecoin source code repository), you’ll see a big bunch of code. As of this writing, it looks like things haven’t changed much since November 7, 2021. That’s true in one sense, but it’s not accurate.

The way Git and other source code management systems work is like a tree. A literal tree, a family tree, a computer science data structure, all of these exhibit the characteristic that there’s a trunk and branches, and everything in the branches relates to the trunk and to each other, but the closer two branches are to each other, the more similar they are in important ways that are less important because that’s where the metaphor starts to lose its power.

You probably know that Dogecoin 1.14.4 and 1.14.5 came out last year. These are new versions, and they’re pretty similar to each other, in the same way that 1.14.6 will be similar.

There’s also a version 1.21.0 in progress, but it’s a lot more different from anything in the 1.14 series than the versions in that series are to each other.

Git and GitHub help us keep these things separate while keeping track of how they’re related by using a concept called branches.

If you look back on the GitHub page, you’ll see a little drop-down widget that says master with the label “12 branches” next to it. Click on the widget and you’ll see a list of other items you can select, including 1.14-maint and 1.21 and 1.14.6-dev. For each of these branches, including master, you can now click on the link to the right of this section reading something like “13,953 commits” to look at a reverse-chronological entry of all changes that have been applied to the code.

Go back to the metaphor I mentioned a few paragraphs ago. Each of these branches relates to the trunk (here called master) but can diverge in some important way.

For example, Misha’s pull request builds on other changes in the 1.14.6-dev series. His changes might be the exact same changes if he’d built them on the master branch or something in 1.14-maint, but probably not.

There are lots of good reasons why developers use branches, mostly around making sure our work is organized, easy to release, easy to think about, and unlikely to make us step on each others' toes.

Why Do Branches Matter To You?

This is all well and good, but if you’re not already an experienced developer, what does this mean to you?

First, if you’re wondering what’s going on with development and someone sends you to the GitHub repository, you have to remember that development work isn’t happening in the master branch which is the default view you’re going to end up on at dogecoin/dogecoin. You have to pick a different branch from that drop-down widget to look at the history (the “13,953 commits” link).

Second, if you’re interested in contributing to the repository, whether it’s code, a bugfix, documentation, a typo fix, a translation, a test, a test fix, whatever, you need to know how to create a PR but you also need to be sure which branch you’re working against.

Truth be told, this is something I often forget, even in a professional day-job context, so hopefully me writing it here will help remind me to check the branch I’m raising the PR against consistently.

Third, if you’re interested in helping review pull requests, it’s important to recognize that each PR itself is a branch unto itself. You can check out a pull request locally to make your review and collaboration easier.

There’s a lot more to learn, and I’ve skimmed over a lot of important details, but if you get these basics fixed in your mind before you go on to the more advanced stuff, you’ll have an easier time of things.

If nothing else, this should be enough to help you understand the Branch Strategy section of the Dogecoin Core contributing guide.

Happy hacking!