The Scenario!

I need a top-tier team of developers to work with me on the code base I began months ago.  I will need to manage the contributions of each developer, help to resolve any code conflicts, periodically verify the software builds, and eventually deploy the product to the marketplace.

For this document I will describe the processes needed to setup and manage a source control environment so that my team can collaborate on a really cool mobile video game.

My Mobile Game Development Environment

• SourceTree for Windows version 3.3.6 (Integrated with Bitbucket)
• Bitbucket
• Windows 10 laptop
• ActionScript 3.0
• Visual Studio Code with AS3 Extension

Getting Started – Local Development

Like most developers working on “basement” projects, I began developing my game on my personal laptop.  After many late nights and a more than a few weekends, I developed the game’s basic functionality to the point that I could show it to people and have them play it. 

After getting some positive feedback, and some very important “not-so-positive” feedback, I made changes to the game then sought out more beta testers.  Then by chance I happen to be playing the game in a restaurant while waiting for some friends.  Two guys were looking over my shoulder and began asking questions.  I explained how to play the game and gave them both a try.  I actually had to insist the 2^nd guy return my phone!  He had been playing for several minutes and was determined to try to beat his last high score.

After finally returning my phone, each man immediately offered me his business card.  Both are executives at Ubisoft, one of the most prominent video game companies in the world, which happens to have an office right here in my city!  As I read the business cards, one of the men “John” said, “Vincent, you really shouldn’t wait too long to get in touch with us.”

I followed “John’s” advice, and about a month later we had made a deal.  Part of the deal was my becoming a product manager of Ubisoft’s mobile game department, with my first task of course being the development and push to market of my new game “The CatGame”.

Refining and Formalizing the Development Environment

When trying to productize a ‘basement’ project, a developer needs to try to use modern, industry supported tools.  For example we cannot develop using discontinued (very inexpensive) software, because it will be very difficult to find other developers work on the project.  Developers who want to continue to bring food home to their families need to stay versed in current programming languages and modern software development tools, so before we are ready to build a team and start work, we need to ensure our product can be built using modern tools.

My New Dev Team!

Fast forward four months!  We’ve hired 2 developers to take our game to the finish line: Vinutha Perry and Houchun Chen.  Both developers have extensive programming experience, but not a great deal of scripting experience.  However since both Vinutha and Houchun have a good understanding of object-oriented programming concepts, I am confident both will be able to make valuable contributions fairly quickly.

That being said, I will need to carefully watch their initial contributions.  I will use peer code reviews and take advantage of the source control features of Bitbucket with Sourcetree.

Creating a New Repository in Bitbucket

First is step to create a collaborative development environment is to create a Git repository, or ‘repo’ for the entire team to work from.  Here are the steps:

1. Log in to Bitbucket.
2. In the left pane, locate and click on Projects.

 

Any current projects are listed in the right pane.

3. Click on Create Project in the top right corner. 

The “Create a project” screen appears.  Here are the settings to use:

4. Click on Create project and to create a project called ‘The CatGame’ that is ready for a repo.
5. Click on Create repository.

6. Use the settings as shown in the screen capture above and again click on Create repository.

Cloning the Bitbucket Repo to a Local Computer

Now clone the repo to the local computer.

1. Click on the Create plus sign (+) on the left pane.

2. In the next window, click on the Clone this repository button under Get to Work:

3. In the Clone this repository screen, click on Clone in Sourcetree.

Sourcetree now opens.

4. Accept the default options and click on Clone to create the local repo.

The Sourcetree workspace for the new CatGameRepo appears:

Moving My Code to the New Local Repo

Because all of my original code is on this machine, I can simply use the Windows File Explorer to copy the source code files to the new repo.

1. To open the repo in File Explorer, I click on the Open in Explorer button.

Now from prior experience I know that once a file is put in the new repo folder it automatically shows in the Sourcetree workspace.  

Before I copy all of my source files to the repo, I want to make sure that my team can collaborate.  To test this functionality I add 3 files to the local repo and push them to the master branch on the Bitbucket server.  One of the files is a basic text file which we’ll use for our tests.

Here’s what the repo looks like after files have been successfully pushed from a local repo:

Verifying Collaboration

When a developer starts her work for the day, she has to assume that work was done on the project while she was asleep, so the first thing that she needs to do is a Pull from the remote repo.

At this point I know this is not necessary, as I am the only person in the system.  However there’s no bad time to start good habits, so I’m going to do the Pull just to watch the results.

1. In Sourcetree I click on the Pull button on the menu on top of the workspace.

Our goal is to pull everything from the remote master branch to our local master branch:

2. I look in my local repo folder to verify the results.

As expected, the Pull executed successfully, and No changes appear in my local folder.  This is because there were no changes to the remote repo.

Simple Change by Developer Vincent

I start be creating a new branch for my changes.

3. In Sourcetree click on the Branch button.  The “Branch” dialog box appears.  I name the branch “Branch-TestCollaborate”.

4. Click on the Create Branch button.
5. Using the Notepad text editor I open the file src/TestCodeFile.txt and add another line of “code”: a simple line of text.
6. I save the change to the file.

This simple change simulates a developer making changes to a core (Actionscript) file. 

In this scenario, the developer made some code changes, tested them in his local environment, and concluded that the changes meet the use case requirements, so now it’s time to push the new code to the common repo.

As expected, the Sourcetree workspace shows the edited file.  The Sourcetree interface clearly shows the new line of code, giving the developer a chance to deny the change.

7. Click on the Stage hunk button to stage the edits to the file.
8. Commit the changes, with a simple commit comment “Added some code.”
9. Click on the Push button to move the changes to the Bitbucket server.

The “Push : catgamerepo” dialog box appears:

This step moves the local branch “Branch-TestCollaborate” to the remote server.

10. Ensure the local branch is selected so that it appears under “Remote branch” in the right column.
11. Click on Push.
12. On the Bitbucket remote server I verify the creation of the new branch by looking at the Commits:

Next we need to merge the new remote branch to the master branch. 

13. Click on the Branches button in the left pane, then click on “Branch-TestCollaborate”.

14. Click on the Merge button.  The “Merge changes” dialog box appears:

15. Select “Close source branch” to remove the remote branch after the merge is successful.

After the merge succeeds, I verify that the remote branch has been removed, and in the Commits view I see that the branch was merged into the master:

Simple Change by Developer Vinutha

As the Bitbucket Admin, once Vinutha and Houchun accepted our offers of employment, I had set up their Bitbucket accounts. 

I then walked them both through the process of getting Sourcetree installed and configured on their local laptops.  The catgame repo has been cloned to their local environments, so now the games can begin! (No pun intended).

To verify our team’s collective knowledge about source control.  I asked Vinutha to make a simple change to the test file src/Test-Collaborate-1.txt.

Verify the change in Bitbucket

When Vinutha completed the change she notified me, so I then returned to Bitbucket/Sourcetree to verify.  First I checked Bitbucket:

I saw on the repo page that Vinutha did make a change and she correctly entered a commit message.

I also drilled down and opened the text file to see the actual change:

So now I know that collaboration works, albeit with a very basic example.  Now what is needed is that all the developers on this project need to update our local repos with the new change.

Update Local Repos with Latest Changes

I returned back to my Sourcetree app and I saw that there is one change to the master branch that is not yet in my local repo:

I clicked on the Pull button.  After the pull request succeeded I can see Vinutha’s update in the History window, and in my local directory.

So now I know that Vinutha can edit any of the Actionscript files in the remote (shared) repo, upload her changes, and then other members of our team can download the updated files into our local repos. 

Making Changes on a New Branch

As we get cranking, adding lots of new features to the CatGame, many of our changes will not be as simple as adding a text line.  Several existing files will need to be modified, while new files will be added.  Hundreds of lines of code will be added/changed.  We’ve got to make sure we don’t break anything in the process!

So we’ll use the pull request feature in Bitbucket for code review.  Here’s a summary of the process each developer needs to use:

1. Ensure the local repo is in sync with the master branch in the remote repo.
2. Create and check out a new branch with the name of the bugfix/feature to be worked on.
3. Update, add, commit, and push the changes.
4. Create a pull request to get the code reviewed by one or two peers.
5. Resolve any feedback. The code updates appear in the pull request.
6. Merge the pull request. You may have to resolve merge conflicts if others have made changes to the same file(s). 

I’ll demonstrate the above steps on another cosmetic change. 

1. In Sourcetree, ensure you are on the master branch and that your local and remote branches are in sync.
2. From Sourcetree click on the Branch button.

3. The “Branch” dialog box appears. Create a new branch called “CGM-Bugfix-001” and click on Create Branch as shown:

4. I refresh the Sourcetree window (F5) so I can see my new branch.

NOTE:  By default the option Checkout New Branch is selected when we create a new branch using Sourcetree.

Now I’m ready to add my changes. 

5. I create one new file and edit an existing file. Here’s how the two unstaged files look in Sourcetree:

6. I stage and commit each change individually so that I can add a unique comment for each.

I can now see in the Sourcetree History window that the files have been added.  Now I’ll push the new branch to the remote repo.

7. I click the Push button and select “CGM-Bugfix-001”.

8. Click on the Push button.

As a result the new branch “CGM-Bugfix-001” is now on the Bitbucket remote repo.

Developer creates a Pull Request

Now that my new branch has been moved to the remote repo I can have another developer review it.  I can create a pull request since I used a separate branch for my changes.

1. From the CatGameRepo on Bitbucket, click on the + button on the blue global sidebar and select Create a pull request under Get to work.
2. I keep the default settings, but add an extra line in the Description field, and select Houchun and Vinutha as reviewers.

3. Next I click on the Create pull request button.

The pull request named “CGM Bugfix 001” is created and emails are automatically sent to Houchun and Vinutha asking for their review. 

When Vinutha is ready to review the pull request, this is how it will look to her:

4. Vinutha approves the cosmetic changes, and Houchun does the same. Again Bitbucket notifies me by email when these approvals are made.
5. I return to the repo and see that the pull request has been approved, and the comments of the reviewers.

Now that 100% of the reviewers have approved the pull request, I’ll merge the branch “CGM-Bugfix-001” into the master branch.

Developer and Repo Admin Vincent merges the pull request

1. From this same page click on the blue Merge button.

 

The following screen appears:

As shown we are trying to merge our branch “CGM-Bugfix-001” into the master branch. 

When needed we can add more comments in the Commit message input field.

By default “Close source branch” is checked.  I’ll leave this checked so that after the merge the developer branch “CGM-Bugfix-001” is removed from the list of repo branches, cleaning up our repo.

2. Next click on Merge.

The merge is successful. 

3. When I click on the Branches button   in the left pane the branch “CGM-Bugfix-001” is no longer there.
4. When I click on the Pull Requests button I see that no open pull requests are present.
5. I click on the Commits button . In the right pane I see the separate branch in red (CGM-Bugfix-001) was created on 2020-07-28, then merged into the master branch “4 hours ago”.

After confirming the merge, I tell all the developers to pull the latest code from the master branch to their local copies using Sourcetree or the command line.

Developers Vincent and Vinutha work on the same file

Next I need to be able to test conflict resolution, which is something unfortunately quite common when multiple developers work on a project.

In numerous assignments over the years I have seen this scenario.  For example in my former company “ABC Incorporated, Inc”:

• Developer 1 (Andry) is assigned to fix a bug. He is working on js, file2.js, and file3.js.
• Developer 2 (Blake) is adding new functionality. He is working on js and file4.js.
• Blake finishes his work then checks in his files.
• Andry finishes his work then tries to check in his files.
• Andry is unable to check in all of his work. There is a conflict in js.

Houston, we have a problem – Merge Conflicts

What happened?

Blake checked in file3.js, which both he and Andry were working on.  When Andry was ready to check in his changes, he was supposed to first do a pull from the remote repo to get Blake’s changes, then add his (Andry’s) bug fix changes.  This happens because sometimes there is missed communication among developers, especially when there are many developers working on a large project. 

Andry didn’t know that Blake’s changes were already in the remote repo, so Andry didn’t think to do an additional pull before adding his changes. 

In our case something similar has occurred.  Vinutha and I were both working on the file TestCollaborate-1.txt.  Having considerably more familiarity with the code in The CatGame, I was able to implement my changes fairly quickly and checked in the new code.

However Vinutha, who had checked out the prior version of the file before my changes, has added her changes to that now outdated file.  When she attempts to merge her pull request, she is notified of the conflict.

Here are the detailed steps that result in the merge conflict:

1. All developers do a pull request to get the latest code.
2. Vincent creates a new branch to add some new features to TestCollaborate-1.txt.
3. Vinutha creates a new branch to add some different features to TestCollaborate-1.txt.
4. Vincent finishes his changes and they are approved.
5. Vincent merges his pull request.
6. Vinutha finishes her changes and they are approved.
7. Vinutha attempts to merge her pull request but it fails and she is notified of the conflict.

Vinutha should have done another pull from the master branch, compared her original source to the latest version, and then added her changes to the latest file.

This is Vinutha’s pull request.  Note the conflict notifications:

Resolve the Merge Conflict

The file TestCollaborate-1.txt shown in Vinutha’s pull request has markers that identify the conflicts.  Vinutha needs to manually merge Vincent’s changes and hers.

In the above screen capture, A is the start of the conflict.  The lines beginning on A are in the main branch, and represent the new code added by Vincent that is not present in Vinutha’s file.

B represents the end of Vincent’s changes in the master file and the start of the new code Vinutha wants to add.

C is the end of Vinutha’s new code.

To fix these conflicts, Vinutha needs to generate the conflict version of TestCollaborate-1.txt to her local computer, edit it, and then update the pull request. 

Using the Git CMD window, Vinutha needs to do the following:

1. Go to the local directory that corresponds to her development branch.

$ cd C:\Users\VinuthaP\Documents\catgamerepo\src

2. Ensure she’s working with the latest version of the Bibucket repository.

NOTE:  For easier documentation we are using “$” as shorthand for “C:\Users\VinuthaP\Documents\catgamerepo\src>”.

$ git pull

3. Checkout the source branch.

$ git checkout TST-MergeFail-VP

4. Pull the destination branch into the source branch. This will try to merge the destination with the source and create a conflict file similar to the one shown in the Bibucket UI. 

$ git pull origin master

Here is what Vinutha sees:

* branch            master     -> FETCH_HEAD
Auto-merging src/TestCollaborate-1.txt
CONFLICT (content): Merge conflict in src/TestCollaborate-1.txt
Automatic merge failed; fix conflicts and then commit the result.

At this point TestCollaborate-1.txt is now a Conflict file.  

5. Using her favorite IDE, Vinutha edits the file so that it looks like this:

6. Commit the changes.

$ git add TestCollaborate-1.txt
$ git commit –m’vp:manual fix of conflicts’

7. Push the changes to the remote feature branch.

$ git push origin TST-MergeFail-VP

NOTE:  Steps 6 and 7 can also be done using the Sourcetree interface.

Now when the pull request is viewed, it will still be open but there will no longer be any merge conflicts.  Since Vinutha’s new code was already approved, she can now merge her branch into the master.

8. Click on the Merge button on the pull request.

After the merge is complete the source code in the master branch is updated, and Vinutha’s branch “TST-MergeFail-VP” is no longer there.

Now all of the developers can go to the master branch to update the code on their local repositories.

Summary

I created this document to show how a lead developer or Project Manager can create a Bitbucket repository, set up accounts for other developers, add code to the repository, and collaborate on a project with other developers. 

This document demonstrates Bitbucket feature branches and pull requests to enforce peer reviews.  I also simulated a merge conflict and detailed the steps to resolve it. 

If you have any questions about the content of this document feel free to contact me at hvharriott@hotmail.com or vharriott@vh-enterprises.com