Revision Control and You – Keeping Your Project Safe

in Tutorials

by taarna23 (original source) (Learning Together Tutorial, Winner 3)

 

Purpose of this Tutorial

I’ve decided to write this tutorial out of seeing this increasing need for people to back up their projects. I can’t actually stress this one enough. Back up your projects! At least once a week I see something like “help, my PC crashed and my files are corrupted!” Did they have a backup? Nope.

So, this tutorial is to help people make sure they have a backup. Not just a copy on Dropbox or some such, but real, proper version control.

RCS – Revision Control Software

It sounds complicated, I know, but it’s really pretty simple. Revision control software, when used correctly, tracks all changes made to all files in your project, who made those changes, when and even allows you to go back to any change on any file throughout the history of your project. Pretty cool, right?

“But wait,” I hear some people saying, “isn’t that just for big companies and huge software? That’s way to big and complex for someone like me. And probably expensive, too!”

Not really. Keeping your project’s files and progress safe should be your number one concern. Not getting feature x, y, or z in. Not getting your demo out. Keeping your project safe. It’s really easy to give into enthusiasm and dive into development, but if you’re not working to keep your files safe, then disaster is quite easily right around the corner.

Bitbucket – Free, Easy and Private

Most people have heard of Github as a place to store their projects, but I tend to prefer using Bitbucket for one simple reason: Bitbucket can have private repositories for free, while Github cannot.

What does this mean to you? It means that unless you have a paid account with Github, your project will be stored in such a way that anyone can come along and pull your project files, assuming they find your project. To me, this is not ideal. I want my project files to be mine until I decide otherwise.

So, for this tutorial, using Bitbucket, and their associated tool SourceTree (covered later) is what we will be looking at. Github is probably pretty similar, but you’ll have to pick a different tool to work with revision control.

Bitbucket Registration

Registering for Bitbucket is pretty much what you would expect for registering for a website. Head on over to https://bitbucket.org/account/signup/ to register your account.

The Dashboard

Once you’re registered and logged in, Bitbucket will take you to the default main page – the Dashboard.

01-dashboard-png-a166415e1cb0ee55ca90b420464c3f0c

The Dashboard gives you an overview of your projects and gives you quick access tot e various sections of the site that you’re most likely to need to use.

Repositories – This section shows a list of repositories you have access to, showing both your own repositories and ones you can access as a team.

Pull requests – A pull request is used when someone generally not directly related to the project makes a change to the code and would like it to be taken and made part of the project. This is generally used with open, public projects.

Issues – This is the area potential issues can be logged so that developers can find and squash these bugs. Or, as sometimes happens, squash the issue report, as it was just user error.

Snippets – This is a place where commonly-used bits of code can be stowed for future use. In this case, perhaps some of the more common script calls could be saved here for reference.

Creating a Repository

02-newrepo-png-37c122128e0dc47601b1f8d00d18056b

To create a new repository, Click Repositories at the top of the page, and click on Create Repository. This menu also shows the recent activity for your current repositories.

03-createanewrepository-png-8bf74fd80b675335a0ff2beee440fa37

The basics of creating a new repository are simple – Really, you only need to give it a name and click the Create repository button. The advanced settings can be used to set more options, but those are outside the scope of this tutorial. After you’ve clicked Create repository, you’ll be taken to your repository’s page. Next, we’re going to need to grab SourceTree, the software that will be used to manage your project.

SourceTree

SourceTree is a piece of software that will help you manage your project’s repository and files. It allows you to review changes to files, compare changes in files, and upload your work to your repository.

To download SourceTree, click the link on your new repository page, or head on over to http://sourcetreeapp.com/.

When setting up SourceTree or a repository, it may ask you for an SSH key. Just click Cancel on that window (despite the fact that it tells you that you can click No).

Setting Up Your Repository in SourceTree

The new repository page does have a Clone in SourceTree button on it, but if your luck is anything like mine, clicking that will do absolutely nothing. If it does work, I don’t really know what to tell you to do next – it never has worked for me!

04-sourcetreeclone-png-e8d6c84b1602900f87fc2156103bbc59

After clicking the Clone/New button at the top of SourceTree, The Clone/Add/Create Repository window pops up. Click the small globe icon button to the right of the Source Path/URL field and in the window that pops up, select your new repository and click the OK button. At this point, you can change the Destination Path if you want, just remember where you move it to. When finished, click the Clone button and your repository will be added to SourceTree. After the repository is added, a window will pop up prompting you for a name to identify you in this project, as well as your email address. These are required so that team members will know who made what changes, and so that in a team setting, members can be contacted about repository changes.

SourceTree Commands

Once you have a repository set up, there are a few commands you will need to know when using SourceTree. These are Pull, Commit and Push. We’ll go over the actual use of these commands and seeing what they do in practice later. For now, here’s a short outline of their functionality.

The Pull Command

The Pull command allows you to obtain any updates to a project that exist on the server, but not on your local copy. If you work with a team, or you work on more than one computer, it is extremely important to do this to prevent a mismatch or conflict (more on this subject later) of files.

The Commit Command

The Commit command allows changes you’ve made to be tracked by your local version control, but without being followed by a Push command, they will remain only as tracked local changes. Keep in mind that when working in a team or across multiple computers, committed changes will not be visible until they are sent to the server using the Push command.

The Push Command

The Push command takes all committed (see above) changes and sends them to the server. This is often done when completing a feature, reaching some kind of milestone, or even just at the end of the day or work period. When working in a team, it is considered polite to not push broken features, but rather, wait until they are complete, or at least semi-functional and unlikely to interfere in another’s work.

Preparing Your Project

You might wonder why a project needs a level of preparation, and the answer is quite simple – space. Every single time you push your changes to the server, the current files are backed up and the new ones are added in. If this is done with large files, such as music or large parallax maps, the size of your overall project storage will increase quite quickly. These files are best stored elsewhere and backed up by a means of your choosing – but do be sure to have a backup.

Note: This tutorial will only cover preparing a new project using RPG Maker MV.

Create A New Project

Create a new project in your Maker of choice (I will be using RPG Maker MV), and save it in a location separate from where you created the local folder for your repository. We will copy the files into the repository after preparing the project.

Remove Unnecessary Database Entries

Open up your new project, and remove everything that is not needed – tilesets, animations, actors, enemies, troops… the works. Most important, however, is to clear out the system-related sounds and music – things like the default battle music, ship music, and various menu sound effects.

05-databasesystemscreen-png-662da5a8fc5b78a997888ce15672262c

Make sure you clear out those Music and Sound sections – unless you know for sure you’re going to be keeping them. Additionally, clear out the Vehicle Images, and even the images for the SV Attack Motions. Remember to set the Title Screen image to none and/or uncheck Draw Game Title.

If you do plan to use parts of the RTP, feel free to leave them in, but do remember that you will need to selectively delete files from the project folders so that you don’t remove those. Ideally, if you have a single actor with no graphics set on that actor, your project should still be capable of running without crashing. If any of the system files are removed without changing them, the game will not run and will inform you of what file is missing.

06-databasesystemcleared-png-f302b12820cbf50adc2e31103c4e5e1e

After removing everything from the system page of the database, it looks more like this. Don’t forget to check all other pages of the database, and remove default things that won’t be necessary for your project. Do remember that if you are using the RTP, you may not need to remove as much as this tutorial assumes. However, it may still be easier to remove everything and add things back in as you find you need them. If you plan to replace the icons, it may be easier to leave the Attack and Guard skills, and simply remove their icons – these two skills need to be exactly where they are within the database.

Note: Animation graphics take up a lot of space. Removing them is a good idea, and you can always add individual animations (on the Animations tab) by copying the needed graphics file into the correct folder, creating a new project and copying from the Animations tab of the new project into the Animations tab of the cleaned out project. This has been tested, and does work – you need only have the two projects open side-by-side.

Remove Unnecessary Files

After you have finished cleaning out the database, it’s time to clear out all unnecessary files, bringing the overall size of your project down to surprisingly small. There are a number of files and types that need to be removed – unneeded plugins, graphics, music, and sounds. These are all in different folders, but you also need to make sure you leave the folders in place.

Folder Listing

The following is a list of folders that will need to be examined. It is assumed you will make your way to these folders from within the new project’s main folder. To reiterate from earlier, these locations apply to RPG Maker MV.

  • audio/bgm – Contains music files in .ogg and .m4a formats
  • audio/bgs – Contains background (ambient) sounds in .ogg and .m4a formats
  • audio/me – Contains music effects (like victory fanfare) in .ogg and .m4a formats
  • audio/se – Contains sound effects in .ogg and .m4a formats
  • icon – Contains a single PNG file to act as your project’s icon
  • img/animations – Contains files for effect animations in .png format
  • img/battlebacks1 – Contains battle background floors in .png format
  • img/battlebacks2 – Contains battle background walls/etc. in .png format
  • img/characters – Contains actor, NPC, doors, etc. animations in .png format
  • img/enemies – Contains front-view enemy battlers in .png format
  • img/faces – Contains actor/NPC face sets in .png format
  • img/parallaxes – Contains parallax background images in .png format
  • img/sv_actors – Contains side-view battlers of the actors in .png format
  • img/sv_enemies – Contains side-view enemy battlers in .png format
  • img/system – Contains system-related images
    • Note: Most of these are required for your game to run. The weapons images may be removed if they have been cleared from the database. Other images should be left in place or replaces with project-specific images.
  • img/tilesets – Contains tileset images in .png format
  • img/titles1 – Contains base title screen backgrounds in .png format
  • img/titles2 – Contains title screen overlay images in .png format
  • js/plugins – Contains some plugins by default. None are configured by use for default.

With the above folders cleared out (with the noted exception of the img/system folder), your project will now be quite small, and is ready to be set up as your first commit and push to Bitbucket!

Adding Your Project to Revision Control

At this point, your entire project folder, or just the contents of that folder, can be added to your repository’s local folder, which we set up before cleaning up a new project. Either way is perfectly valid, and if you’re working in a team, should be agreed on by the team members. Find your repository folder and copy either your project folder, or all files inside that folder into your repository folder. When you do this, your changes will show up inside of SourceTree as Unstaged files. What this means this time is that the revision control software doesn’t know about these files, and is unsure if it should include them all, so it is waiting on you to choose. New files added or altered later on will also show as unstaged files, which will give you the option as to whether or not you want to check them in at that time.

07-sourcetreeaddprojectfiles-png-ce300d23e3292477b5cc04b12bca789d

Seeing as we need all of the files, click the Stage All button. The files will move up into the Staged files section.

08-sourcetreereadytocommitpush-png-a03a4eb37a25c1373396a47ee5081f93

The last step is to give this commit a description and then push it to the server’s repository. Remember that all commits should be given detailed descriptions so that you can refer to them in the future and know what was changed, and in some cases, why it was changed.

Check the Push changes checkbox below the description field, and click the commit button. After it’s done and you close the status window, SourceTree will now show that there is nothing to commit.

Note: If you forget to check the Push changes checkbox, the only difference is after you’ve clicked the Commit button, you will need to click the Push button on the ribbon at the top of the window.

09-sourcetreefilescommittedandpushed-png-100cd7c442ea8549dbcbc2c32bac5040

That’s it! …mostly.

For the most part, that’s all there is to using SourceTree and Bitbucket. If you’re working on your project across more than one computer, or you’re working as part of a team, you’ll need to use the Pull command, which goes to the server and gets all files that have changed between the version you have and the version it has. In these cases, it is extremely important that you use Pull before starting work on the project, even if just to confirm there are no changes. If you do not, it is possible the work you do will cause a Conflict.

Conflicts

Sometimes when more than one person is working on a project, there will be problems called Conflicts. This occurs when two different versions of the project both show different changes to the same file. Through some kind of magic awesome technological stuff I don’t entirely understand, the system knows the difference between your changes to a file and someone else’s changes to that same file. Unfortunately, due to the nature of many, especially older, RPG Maker files, the process called merging is extremely difficult or downright impossible to do. In the case of a conflict, your only options are to use the local (your changes) or remote (someone else’s changes) version of the file. If you are working in a team and a file conflict occurs, talk it over with your team before blindly overwriting the remote files.

Updating With Your Changes

When working on your project, you can work directly with the files in your local copy of the repository. SourceTree will track any changes you make and is always ready to help you get them into revision control. Afterward, it’s the same process as the commit and push of the original project – give it a description, check the checkbox and click Commit.

Looking Back

You can look back at the history of your project at any point in time by selecting your repo on the far left side, clicking the little toggle arrow beside origin under Remotes (if it’s closed) and clicking on master. Master is the main “branch” of your project, and assuming you have not made other branches, is all that will be listed in here. In the main window to the right, a list will be shown of all commits to all branches of the project. If you have multiple branches, you can select which one to view information on.

10-sourcetreeremoteschangeslisting-png-e9ad58e58b921fd365454cfacb8ab82e

Note: Branches are not covered in this tutorial, but they are generally used to develop large new features of a project and are either left as branches for any number of reasons, or are merged back in with the main project.

That’s it!

So, that’s really all there is to it. Once you have the basics down, it’s really easy. From there you just need to remember: Pull, do your work, commit and push. Do those steps every time and you should have no problems at all!

If you’d like to download this tutorial as a document file, here you go: Revision Control and You.docx

Comments on this entry are closed.