DNN Community Contributors Guide

In order to facilitate collaborative development on any DNN project, a clear and consistent branching strategy has been adopted. This strategy consists of maintaining two permanent branches in each main Git repository: master, which represents code that is assumed to be in a release-ready state, and develop, which contains work to be incorporated into the "next release". However, there are a number of important supporting branches that will only live for a limited amount of time, including feature branches, production hotfix branches, and specific release branches. Though they are normal Git branches, they differ significantly in the way they are used in the development process.

The Permanent Branches

The master branch should be familiar to any Git user, representing the stable, production-ready code in the repository. In our process, we maintain another branch with an infinite lifetime, develop. You can think of this as the "integration branch" where all changes are delivered for the next release.

When the code in develop reaches a stable point and is ready to be released, all of the changes will be merged back to the master branch and tagged with a release number. Each merge commit back to master represents a release, by definition.

Supporting Branches

There are a number of supporting branches in our process that are used to aid in collaborative development of bugfixes, translation updates, features, preparing releases, and quickly applying patches to production releases. These branches are referred to as:

• Feature branches - these are the branches that you will be working with as a community contributor
• Release branches
• Hotfix branches

Each has a special purpose and strict rules governing origination and merge targets, but are otherwise normal Git branches.

Working with your GitHub fork

Project contributors must work directly with their private forks on GitHub. Here is the suggested way to prepare your local repository (example uses Git Bash for a project named ActiveForums).

$ cd YourDotNetNukePath/DesktopModules
$ rm -r ActiveForums	
$ git clone git@github.com:YourGitUsername/ActiveForums.git
$ cd ActiveForums
$ git remote add upstream -f http://github.com/jbrunken/ActiveForums.git

This setup makes your fork the standard origin remote, and adds/fetches the "blessed" repository as the remote upstream. You may want to add other remotes to other developer forks as well, and I would name those remotes appropriately so you can keep track of each one.

You'll want to go ahead and create local tracking branches for the permanent branches from your fork, a.k.a. origin:

$ git checkout -b master origin/master
Switched to a new branch "master"
$ git checkout -b develop origin/develop
Switched to a new branch "develop"

To keep your local tracking branches for develop and master up-to-date from the upstream repository:

$ git fetch upstream
$ git checkout develop
Switched to branch "develop"
$ git merge --ff-only upstream/develop
$ git checkout master
Switched to branch "master"
$ git merge --ff-only upstream/master
$ git push origin develop master

Note however, that the push is mainly for show, as the permanent branches should never be a target for contributor commits, even in the forks. IOW, develop and master in your fork should always match the upstream branches of the same name. It is expected that all contributions will be submitted via a feature or hotfix branch originating from the appropriate permanent branch, or a bug fix branch originating from a release branch in the upstream repository.

Also note the --ff-only flag ensures that only fast-forward merges are performed (in case you accidentally do commit to the main branches on your fork without realizing it).

Feature Branches

• May branch from: develop
• Naming convention: anything except master, develop, release-, or hotfix-

Feature branches are used to develop a specific new feature (or set of features) for the next release, or for a future release. The target release for the feature to be incorporated may well be unknown, and the branch will exist as long as that feature is in development. Once it is accepted and ready to be incorporated in the next release, it is merged into the develop branch by an integrator. If the feature is never completed or accepted, it can simply be discarded.

Feature branches typically exist in developer forks, and only for sharing purposes, not in the "blessed", or upstream repository.

Creating a Feature Branch

When starting work on a new feature, branch off from the develop branch.

$ git checkout -b myfeature develop
Switched to a new branch "myfeature"
Submitting a pull request for a finished feature

Once you have completed development of a feature on a branch, you should first make sure your work is replayed over the latest updates from develop:

$ git fetch upstream
$ git checkout develop
Switched to branch {{develop}}
$ git merge --ff-only upstream/develop
$ git checkout myfeature
Switched to branch "myfeature"
$ git rebase develop

This will make it easier for integrators to incorporate your work without conflict.

Now simply push your feature to your fork (you can do this early on if you want to share your feature branch for collaboration):

$ git push origin myfeature:myfeature

And you are ready to submit a pull request for your feature branch.

---

Note: This content was borrowed liberally from this page.