new Using Bitbucket for I&A development: a guide

[danne]

Alright. I've set up the Bitbucket repository for I&A2 to include the history of most versions up to now. There are probably gaps and other strangeness in the commit history, but the most important is the latest version.

 

First thing you need to do is to sign up for a free Bitbucket account.

 

The easiest way to use Bitbucket is to first download and install SourceTree:

 

When first installing SourceTree a guide will popup and probably another window "SourceTree: Mercurial not found". I&A2 use GIT instead of Mercurial so you can safely select the "I don't want to use mercurial" option. That will close that dialog and you are now probably looking at the setup guide.

• Fill in your information and check all boxes and click next.
• SSH Client Cinfiguration: Use the recommended option (PuTTY/Plink). Next
• Load SSH Key: No
• Now add proper account information. If you want to do stuff with I&A3 too you'll have to create an account on github and fill out those fields as well.
• Finish!

 

Next step is to get the code to your computer. Follow theese steps even if you already have a current version on your computer.

• Go to I&A2 repository on Bitbucket
• If your left sidebar is narrow you can fold it up by clicking on it. It will then expand and you'll see some "Actions" on the top.
• Click clone and select "Clone in SourceTree" ( a big blue button).
• A dialog will open up in SourceTree "Clone New".
• Wait for it to load everything.
• Change checkout branch to "develop".
• Change Destination path to something like this: C:\Users\<your account>\Documents\Arma 3\mpmissions\co45_AW_Invade_Annex.altis       (don't use an existing folder)
• Keep a bookmark of it and change the name of the bookmark if you like (tip: keep it short)
• Press "Clone" and wait for it to download.
• Select "develop" under "Branches" in the left sidebar.
• You now have the latest I&A on your computer and if you put it in a destination Arma recognises you can start it up in ARMA. and edit scripts with your favourite editor.

 

Now you are ready to do some editing!!!

Before you start, consider this:

It's easier to track changes if you make commit every feature change you've made. Edited missions.sqf in ARMA editor -> commit. Changed some setting in VAS -> commit, sone something to lifting script -> commit etc. Also try to use descriptive comments on your commits. This is not mandatory, but makes stuff much easier.

 

Here is a simple flow you can follow.

1. Check if you have anything to pull (downwards arrow in toolbar, will have a number on it if there's anything to pull) and pull any changes someone else might have done.
2. Do some editing. SourceTree will see any changes you are doing ("uncommited changes" in the graph)
3. When you are done. Press commit button in SourceTree.
4. Write a commit message ("Removed static weapons from VAS")
5. Choose the files you want to stage in your commit (press checkbox on the files you've changed so they move up to "Staged changes".
6. Commit!
7. Continue editing (go back to 2) or
8. Check if you have anything to pull. (someone else pushed changes while you were editing)
9. Push your changes to origin (Bitbucket), upwards arrow in toolbar.
10. If it's time for a release, tag a release (I'll explain when we get there)

Things can get a bit hairy if two persons are doing changes at the same time. If you are unlucky an automated merge cannot be done. You can do changes to the same file and manage to merge automatically if there are no overlapping changes.

mission.sqf is automatically generated from the mission editor in arma and will be almost completely different each save even if you've only made small changes. I guess it's kind of important to make sure no one else is currently editing it have them push their changes before you start.

 

We can currently have 5 developers with write access on Bitbucket. That's the limitations of the free account. Other people can still use the repository and make changes locally (pull and commit) and there are ways to get their changes in too. But that is beyond the intended scope of this guide (Read: I'm not exactly shure how to do it myself)

 

 

I'm avaiable for questions and troubleshooting both here and in TS.

 

We should add more stuff on bitbucket too, Mykey's tools, custom game night missions etc, I don't have proper access to create more projects under Ahoyworld, but Raz might be able to get that from Rarek perhaps?

 

It's possible to get the mission automatically to the servers too. We need to install git on the server and make a script that polls Bitbucket, at a sensible interval, if there are any new releases and then fetch that, compress to pbo and put in the correct folder.

 

/danne

[danne]

Actually, after a bit of reading:

A better way is to after you have created an account on Bitbucket and logged in on the site; go to the I&A2 repository and make a fork to your own account and then set up SourceTree by cloning your own fork.That way more than five persons can make edits on the projects if needed and when syncing someone with experience of mergin code can overlook the sync process. That way we can have a core developer group of maximum five people and an unimited amount of contributors via their own forks.

[razgriz33]

Excellent tutorial! thanks so much for taking hte time to write this out! I will be using it

[kamaradski]

That was a lot of writing Danne !

[Jester]

wow, nice writeup danne! now if i can get all of it to sink in....

let me ask you this though, if i sync the files that are in the repo with ones i am editing, i.e. i alter a file, click save, the sync now sees that the file has changed and updates the file in my forked repositorie..... will that then update the files on bitbucket? or do i need to do something for them to update on the website.

 

if it does it auto matically then i dont think i will use an autosyncer. 

[danne]

After a bit of trial and error I've found a workflow that is not too complicated.

A free bitbucket account can only have five developers. To get around that, most people will have to use forks. This is actually a good thing. It adds a few extra steps to the fork users, but it leaves the most complicated code mergings to the experienced people with write access to the main repository.

So what is a fork and how do all this work?
I'll start with the structure of the repository. We have two main branches, master and develop and we are using minor branches in the categories hotfix and feature.

master
The master branch is supposed to reflect what's running on the servers. An update here means there's a release. A main version like 2.78 or a hotfix version like 2.77F.

develop
The develop branch is where all development towards the next main mission is situated. As I'm writing this master and develop is more or less the same, but while we are working towards a new version, this will not be the case. When we are done developing and are ready to release a new version, we will merge develop into master and call it the new version. When you have committed some changes and pushed them to your fork, you need to create a pull request so we can pull them into the main repository. You can do this directly from the commit dialog by checking the buttons "Push commit to origin" and "create pull request" in the lower left corner. Or you can use the menu "Repository"->"create pull request..." or press Shift-Alt-P. More on pull requests further down.

hotfix
If we need to adress bugs or add stuff that can't wait until the next release, we create a hotfix. You create a hotfix by first commit any work you are doing in develop, sync your fork (more about this later) and use "Git Flow" -> "Start new Hotfix" in Sourcetree. Use the name of the version as the name of the hotfix (ie "2.77G"). This will branch off from the main branch as the hotfix is supposed to fix the current version. Now, do the needed changes and commit them, several commits if needed and when you are done, push your changes. Don't close the hotfix in the git flow dialog, this is important. You can however create your pbo and distribute the new version at this stage (don't forget to exclude the .git folder). To put the changes on the main repository you need to create a pull request (see develop above and pull requests below). Someone (probably me to begin with) will then review the changes and finish the hotfix. A hotfix is merged back into the main branch and also into the develop branch. If work is going on in develop this will probably lead to some conflicts and someone experianced to handle them and you can happily go on doing your developing without worries. When the pull request is accepted you can sync your fork and see the results of the merges.

feature
This class of branches is used if you want to add some larger feature to the mission than may or may not end up in the next version or a later version. You will probably not use this, but I'll write something anyway, just in case. I'll take something I'm working on as an example. I have an idea of using the support menu to add tools to admins that will make nss obsolete and add some extra useful stuff in as well (the useful stuff from mykey's play tools like "delete object"). It's a well defined feature that is more than adding some lines of code to a file. I'll need to add several new files, functions and scripts for this, so I decide to make a feature branch called "Admin tools". That means that work on this new feature will not have any effect to other development until it's done. I can jump back and forth between develop branch and the admin tools branch and not mix up the code. When I'm done I'll finish the feature and it will merge back into the develop branch. If the develop branch have changed a lot I could be looking at some serious conflicts to resolve if changes have been made in the same places. So if you are doing a feature branch from your fork, don't finish it (as with the hotfix) create a pull request and leave the merge to me.

So, that's how the branches in the repositories work. Next is repositories and forks.

origin (main I&A2)
This is the "master" repository on bitbucket. This is where all changes should end up so people can see what changes have been made and create their own forks or just to download the current mission.

local
This is the thing you have cloned to your local hard drive. It's your working directory and also your local repository. Any changes to your working files will show up as "uncommitted changes" or "working copy changes" in SourceTree and you commit those changes to your local repository. When you've done that you can push those commits to origin (bitbucket) so other people (probably no one when working on your own fork) can pull them and refresh their code with your changes.

fork
This is a copy of a "master" repository and will function as your origin. In the same way you have to push and pull changes to and from your origin the fork needs to push and pull changes to the master repo so you will have the latest changes and also send your changes to the master repo. You send your changes by creating a pull request. That means you ask to have your changes pulled from your fork by the master. And you fetch the latest changes by making a "remote pull" from the master.

sync or remote pull
Ok. Now on to how to sync your fork. First how to update your fork from I&A master:
First you need to add an extra remote. In the left column you already have your "origin" as a remote, that's your fork. You also need to add I&A main repository there.

• Right click on "Remotes" and choose "new remote" or select Repository->Add remore in the main menu.
   
• In the dialog click "add"
   
• fill in a name (like "main" or "I&A" or something) and a path (https://<username>@bitbucket.org/ahoyworld/aw-i-a-2.git) You can also get a path with some creative copy + paste if you press clone on the main bitbucket page (https://bitbucket.org/ahoyworld/aw-i-a-2/commits/all)
   
• Press Ok and Ok.

Now you have two remotes, your origin and the one you just added. To sync you now have to expand the new remote to see the branches. Now, for all your current working branches (probably only master and develop) do the following:

• Select branch (so you have the bolder text and the checkmark on the arrows icon.
   
• Right click on the corresponding branch in your new remote.
   
• Select "pull <name>/<branch> into current branch"
   
• Push your changes to your fork
   
• done. Go ahead and do your stuff.

Pull requests
When you are done with your changes and want to get them published to I&A main. First push all commits to your fork and create a pull request. You can do this at the same time you are doing a commit or later on via the menu. (When I'm writing this bitbucket seems to have some problems, so I'll do this from memory):

• When you have used the request in sourcetree, a dialog will open. Just click "create pull request on the web" and a browser will open with a form.
   
• Check so the correct branches are selected. Same to same is the rule here. develop to develop, hotfix x to hotfix x and feature y to feature y. Never master branch please. My experience is that you always have to change something even if you selected the correct ones in the dialog in sourcetree.
   
• Write a title if not already pre filled by SourceTree.
   
• Submit form.
   
• Wait. Roll your thumbs, continue coding or whatever until your changes are reviewed and merged into the main repository.

Some things to think about
Sync before you start a new coding session. Start the hotfix in SourceTree before you do any changes. To avoid complicated conflicts wait until your pull request has gone through until you sync again, that will leave the complicated conflicts to me. If you are more people working on the same stuff (like the VR ammo box thing lately) It's better if you work on the same fork. If shit happens, I can help you doing your changes and then you can delete your working copy and create a new fork to work on instead. Remember to exclude the .git folder when creating the pbo. It's probably best to have a different folder where you create the pbo from and copy the contents of your working folder (not .git) to that and create the pbo from there.
If you are feeling uncertain about this it's probably best to use a fork. You can't break anything from a fork :-)

 

Any problems at all. Ask me.
I'm doing walkthroughs in TS if needed and I can also give a cource in more advanced stuff like merging with conflicts and more.

 

 

Another source of information. I can recommend having a quick look at the git tutorial and workflow here: https://www.atlassian.com/git/