It’s been an exciting past few years being a developer in the DNN community. I’ve watched as the ability for developers to contribute bug fixes and features has opened up, to the point where now there are community representatives acting as gatekeepers, and working to accept the community’s contributions to the project. Being passionate about contributing to open source projects in general, and specifically contributing source code to the DNN Platform, I was honored to be selected to give a presentation at DNNCon 2014 on just that topic. You can view the presentation slides on GitHub, and there should be a video of the presentation, as well, before too long.
The talk is split into two fairly distinct sections. Firstly, I spend some time talking about effective communication and collaboration. The first step in contributing to a project is making sure that you’re actually being helpful, ensuring that your contributions are on track with the project’s vision, and that your contributions are in a format that are easy to digest. If you consistently provide contributions which are as much work to review as they are to write from scratch, you’re not going to endear yourself to a project’s maintainers. This starts with thoughtfully complete bug reports, through to engaging the community around feature ideas, and being humble and positive throughout your interactions.
Getting to Know Git and GitHub
The second half of my presentation centers around the tools used to collaborate on source code, namely Git and GitHub. Git is a tool with a fairly large learning curve, but, as someone towards the top end of the curve, I emphatically recommend learning it and using it for every kind of version control need you may have. In terms of getting your feet wet, you can use the GitHub website to easily submit changes to single files in someone else’s repository. For example, I can go to the DNN Platform repository, navigate to the
IFileInfo class, click the Edit button in the top right, add some missing documentation, fix a typo, and then a couple of clicks later, submit that change as a pull request to DNN.
To go beyond that, you’ll need to setup a development environment locally on your computer. This first means installing Git (I suggest Git Extensions as a great Git tool, giving you access to commands via clicks and for helping to visualize your git repositories; other folks like SourceTree, as well). Secondly, you’ll need to clone the git repository. From the command line, that’s
git clone https://github.com/dnnsoftware/Dnn.Platform.git, which will create a
Dnn.Platform folder with the contents of the repository (including a hidden
.git folder with the entire history of the repository). From there, you’ll need to get setup to develop a change. The first step is making sure that you’re on the right branch, which you do by checking out the branch, via
git checkout development (where
development is the name of the branch upon which new DNN development is integrated). This should be the default branch of a newly cloned repository, but it’s good to double-check. Next, setup that DNN site, so that you can test any changes that you’ll make later. The default solution (
DNN_Platform.sln) points to the
Website folder via
http://localhost/DNN_Platform, so you’ll want to set that up in IIS. Right click on the Default Web Site in IIS, and pick Add Application. Give it the alias DNN_Platform, and point the physical path to the
Website folder in the Git repository you just cloned. Make sure that the assigned Application Pool is running .NET 4, rather than .NET 2. Once IIS is setup, you can open Visual Studio (grab the free Visual Studio Community 2013 if you don’t have a better SKU), and build the solution. I always build first in Debug mode (though I don’t recall the reason), and then you need to make sure to build in Release mode, as well, which will create the installable packages and put them in the right place in the
Website folder. I usually then build a third time, in Debug mode again, so that I’m ready for debugging, if need be.
You’re now ready to navigate to
http://localhost/DNN_Platform and install DNN (you’ll also need to setup a database to point the site to). Once it’s up and running, you can start to think about making whatever change you want, testing it, and then submitting it as a pull request. Once you’re going to be making changes, you’ll definitely want to create a new branch in Git, so that you can separate these changes from any others. In GitHub, pull requests are between branches, so you want to make sure that you have a clean branch for each pull request. To do this, you can create the branch via
git branch my-bug-fix, and then checkout the branch via
git checkout my-bug-fix. Once you’re used to that, next time you can do both at once with the
-b flag of the
checkout command, i.e.
git checkout -b my-bug-fix.
With your branch setup, you’re now ready to write some code. Once you get to a stopping point, make sure to commit your changes. This is one of the places where a visual tool like Git Extensions is really helpful. It can show you the files that have changed, and what’s changed in them, and help you make sure that only the changes that you expect are in your commit. Git has the concept of a staging area, meaning that your changes have to be staged before they are committed. In a visual tool, this happens fairly intuitively, but from the command line, it means that you need to add your changes (
git add -A), and then commit them (
git commit). When you commit, you’ll need to specify a commit message. It’s good practice to write down what your commit did and why; in addition, if you include the JIRA ticket number (e.g. DNN-4567) in the commit message, it makes it easier for the DNN team to keep track of when changes are associated to an issue.
Git is a distributed source control management tool, unlike many older tools that you may be familiar with (e.g. svn and TFS). This means that when you commit, you’re only committing locally, not publishing that commit to a central server. This gives you a lot more freedom to make frequent commits as you work through a contribution, and only publish them once you’re comfortable with what you’ve done (the fact that the hosting on GitHub is also distributed means that you can also choose to publish early and easily collaborate on code before it’s complete). So, don’t get too nervous about committing; rather, commit freely and often.
Once you’ve solved the problem, and committed all of your changes, it’s time to publish the branch and submit a pull request (i.e. request that someone pull your changes into the main DNN Platform repository). This starts with pushing your changes. To do that, you’re going to have to think about a concept in Git called remotes. Remotes are simply named URLs which point to various repositories. When you cloned the repository earlier, Git created a remote named
origin pointing to that URL. In order to avoid confusion, I like to have my remotes named after the owners of the repositories. So, we can remove
git remote remove origin, and then create a new remote named
git remote add dnnsoftware https://github.com/dnnsoftware/Dnn.Platform.git. You’ll also want a repository owned by you, on GitHub, which you’ll use for submitting your pull request. So, if you don’t already have a fork of the DNN.Platform repository, visit the DNN Platform repository page, and click the Fork button in the top right. This will create your own personal Git repository that is an exact replica of the main DNN Platform repository. Grab the URL for that and add your remote (e.g. if your GitHub username is bdukes, do
git remote add bdukes https://github.com/bdukes/Dnn.Platform.git). Once you have that remote defined, you can push your changes up to your fork, via
git push -u bdukes my-bug-fix (the
-u flag, short for
--set-upstream, tells Git that you want your local branch to track the remote branch, so that next time you can just say
git push and it will know where to go without specifying the remote or branch names). At this point, the changes are up on your fork in GitHub. If you visit your fork’s page on GitHub, you’ll see a helpful green button, offering to submit those changes as a pull request to DNN. In the pull request, include the JIRA ticket number in the title, and feel free to just link to the JIRA ticket in the description (it’s difficult for the team if the information is in GitHub but not JIRA, but it’s fine the other way around).
Getting Ready for Next Time
At this point, you’ve submitted your pull request, and someone will come along and comment on it and/or merge it. Congratulations, you’re a contributor! All that you have left to do is setup your environment for your next contribution. Go ahead and
git checkout development again. Before you do your next change, you’ll want to make sure that your local
development branch is up-to-date with the main
development branch. One of the ways that you make this easy is by never making any commits to your local
development branch, so that you don’t have to deal with conflicts when you try to update it (again, always do your work in its own branch). So, with
development checked out, you can do
git pull to fetch the latest changes, and then move your local branch up to that latest commit.
More Help and Resources
I definitely understand how all of that can feel a little overwhelming. Once you’ve done it a few times, you’ll get into a rhythm (and probably also run into some kind of trouble). I wholeheartedly want to encourage you to keep it up, push through, and try to learn. As much as possible, the DNN pull request team will give tips as we review your pull request, and try to help out if you get into trouble. Additionally, I’ve had the pleasure of getting to learn a lot of this and use it in my daily work life for a while, but that doesn’t necessarily mean that I’m the best at explaining it. A few resources that I’ve found to be immensely helpful in getting to a point where I get Git, and understand what it does, and what it can do include:
Also, Try Git is a good quick, interactive overview of the basics.
A Bright Future
I heard a lot of folks at DNNCon getting excited about making their first contribution to DNN, or getting back into contributing. It’s exciting to see the renewed vibrancy of the community, which was displayed in many different aspects throughout DNNCon. At Engage, we’re all really looking forward to a future full of community engagement and shared ownership of the platform that many of us have built our businesses upon. To that end, Engage is going to be hosting a hackathon for contributing to DNN. For details on how to get involved in St. Louis, or online, see our explanatory post.