How to Maintain a RockWeb Plugin Environment with a fork

If you are Plugin Developer and are comfortable with github, this doc is for you!

Your GitHub Account

First, you need have a GitHub account. You'll need this so we have a place to fork the https://github.com/SparkDevNetwork/Rock repository to. For the purposes of this doc, let's assume you are going to use a personal github account called https://github.com/yourname/ .

Create your Fork

Now that you have a github account, let's Fork https://github.com/SparkDevNetwork/Rock.

1. Login in to github with your 'yourname' github account, then go to https://github.com/SparkDevNetwork/Rock
2. Find the button that says "Fork" and click it. Almost immediately after you click it, you'll have a fork at https://github.com/yourname/Rock

It almost seems too easy, doesn't it. So, why did we do that and what are each of these for?

• https://github.com/SparkDevNetwork/Rock

  • We won't be committing or pushing any changes to this Repository, but we will pull and merge updates from this repository into our fork from time to time. We'll get into the details of how to do this later in this doc.

• https://github.com/yourname/Rock

  • This is our fork of the Rock repository. This is where we will be creating new plugins, blocks, themes, etc. You probably won't be changing any core code though (but you will have full access to it).

Use SmartGit

Create a local clone of https://github.com/yourname/Rock

1. Select File | Clone -
2. Paste the https clone url (https://github.com/yourname/Rock.git) into the Repository URL edit box -
3. Press Next until you get to where you specify the Local Directory Path. Choose c:\github\yourname\Rock and press Next -
4. When prompted to 'Open in new project', choose Rock-yourname as the Project Name. Adding -yourname to the end is important (it'll prevent some confusion later) -
5. Finish (this might take a while)

Make sure you have a local 'develop' branch

Now, look in 'Branches' | 'Local Branches', make sure you have a 'develop' branch. It should look like this:

SmartGit might have automatically did this already for you, but if it didn't, do the following

1. In 'Branches', right click on origin\develop and select 'switch branch' -
2. Choose 'create local branch:' name it 'develop', and enable 'Track remote branch'. -
3. Click switch

Pull from 'origin (https://github.com/yourname/Rock.git)'

With 'develop' as your active branch, Click 'Pull'. This will get the most recent version of 'origin\develop' from your Rock fork.

Add the upstream repository (https://github.com/SparkDevNetwork/Rock.git)

1. Select Remote | Add..
2. Set the 'Url or Path:' to https://github.com/SparkDevNetwork/Rock.git
3. Set 'Name:' to upstream -
4. Click Add

Keep your fork up-to-date using SmartGit

Pull/Fetch from upstream

1. In 'Branches', right click on upstream and select 'pull'
2. Make sure 'Fetch From' says 'upstream (https://github.com/SparkDevNetwork/Rock.git)' then click 'Fetch Only'

Merge from upstream/develop into Local/develop

1. In 'Branches', right click on upstream\develop, choose 'Merge...' - - then choose 'Merge to Working Tree' -
2. If there are any changes, review them, then click Commit, then Push

Pretty easy, right?

Your Visual Studio solution (*.sln)

First, we want to create our own Rock-yourname.sln file by renaming the Rock.sln

1. Using Visual Studio, open c:\github\yourname\Rock\Rock.sln
2. In Solution Explorer, select Solution 'Rock'
3. Click File | Save As, and save it as c:\github\yourname\Rock\Rock-yourname.sln

Now, from now on, open your 'Rock-yourname.sln' instead of 'Rock.sln' (it'll get confusing if you don't)

Adding Plugin-Projects

If you're plugin requires that you write your own .dll, go ahead and add those projects to your 'Rock-yourname.sln'. Name them using the Rock naming conventions. For example, 'com.yourdomain.PotluckDinner'

Adding Plugin Blocks

Create your custom Rock blocks in RockWeb\Plugins\com_yourdomain...

Use SmartGit to keep your fork updated

Now that you have your own fork, you can commit and push all of your changes up to your github fork (https://github.com/yourname/Rock). Typically, the only stuff you would be changing is in your Plugin-Projects, RockWeb\Plugins, and maybe Themes.

Summary

That's about it! Now that you are set up, you'll mainly be doing this from day to day

In the `develop' branch

1. Pull/Fetch from upstream
2. Merge from upstream\develop into Local\develop
3. Code your Plugin Projects and Blocks
4. Commit/Push to origin

Note, if you are developing your plugin/block for a specific release of Rock vs just the latest from develop, the above instructions are pretty similar. Just work in the release branch (for example, Release 1.2) instead of develop.