README

What is this repository for?

Writing a game to teach Telecommunications at the University of Johannesburg

  • The Traditional four or five tutorials covered in a semester should be gamefied.
  • Version 0.0

How do I get set up?

NB: READ AND DO THIS BEFORE ANYTHING ELSE!!

Before you do anything in this project, it is important to sort out some gerrit admin. Please follow EVERY one of the following steps:

  • Go to www.codebreakers.co.za and log in to ensure your username and password works.
  • Follow the link to the Gerrit web interface and register.
  • Add your public ssh key to the Gerrit system. (this step is actually optional. Kinda. However, if you do not follow this step, you have to use http to clone instead of ssh. See explanation under instructions for using gerrit. Finally note, since we added ssl encryption, this hasn't been tested properly and using ssh is strongly encouraged)
  • Ensure you have git installed.
  • Ensure you have vim installed. On windows, installing git will include the git bash shell. It already includes vim.
  • Edit your git configuration file. (This is found at ~/.gitconfig) Ensure that your name and email are set. Your email must be your gmail account. This could be done with a bash command
  • $ git config --global user.email "youremail@gmail.com"
    $ git config --global user.name   
    $ git config --global core.editor vim 
  • Clone the repository. Do this with git on a bash shell: Remember <username> is your gmail id without "@gmail.com" at the end.
  • $ git clone ssh://<username>@codebreakers.co.za:29418/codebreakers
    $ cd codebreakers
  • Inside the codebreakers directory, run the following commands:
  • $ scp -p -P 29418 <username>@www.codebreakers.co.za:hooks/commit-msg .git/hooks

How to git?

Here follows a quick tutorial for using git, if you have no prior exerience whatsever. Note, git relies on getting somewhat comfortable with using a terminal such as bash.

Setting up on Ubuntu/Debian, a simple "sudo apt-get install git" should do it. If you are adventurous, it can be built from source. Go nuts.
For non-debian based system, it should be available in whatever package manager your system uses.

git is a version tracking system, that keeps a complete copy of the entire project, including history, on each user's system. Useful, in case of a server crashing. (Ours is based in Amsterdam at the moment, so we should be safe against Eskom, if they feel like load shedding).

OK. So if you clone a repository from a server, you have the latest version of the entire project and its history. You list the contents of the directory, and see something like the following:

  • humxn.js
  • terrain.js
  • main.js

Say for instance, you want to edit this game, so that the main character has a new superpower, that spouts fire from his/her ears. To do this, say you end up editing humxn.js and main.js. Once you are happy with this new feature, you might run

$ git status

This will output a lot of stuff, amongst others

Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
		
	modified:  humxn.js 
	modified:  main.js

This means that at this point, your changes might be in working order, but unless you take further action, they will not be added to the project, and possibly lost. To prevent such a catastrophe, you need to commit the changes.

Committing is a two step process. First, changed files need to be staged. This is an inbetween state, and provides an easy way to not accidently commit unnecessary files.

$ git add humxn.js
$ git add main.js
$ git status
					

Now, your output should be

Changes to be committed:
   (use "git reset HEAD <file>..." to unstage)
		
	modified:  humxn.js 
	modified:  main.js

If you are happy that these are indeed the files that you edited, and you want to now commit these changes into the project, you can proceed with the second and final step of committing.

$ git commit -m "A nice descriptive message here"

Each commit is accompanied by a message such as above, indicated with the -m flag. Without the flag and message, you will be taken to your text editor to set one, but just including it in the command is much easier.

All changes to this point have been limited to your own system. To get this onto the central repository on the server, one needs to push. To "save" minor changes on the system,

$ git push -u origin HEAD:sandbox/<username>/branch_name

and if you want to push code for review,

$ git push -u origin HEAD:refs/for/master

The "master" is the branch being targeted and can also be some other branch name.

This is a nice intro, and will be expanded more, as there is more to know, but for now, this is a crash course on the basics.

Commit message guidelines for git

Seven rules that should make you a pro:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

Example:

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to a
max of 72. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Use the imperative mood in the subject line

Imperative mood just means "spoken or written as if giving a command or instruction". A few examples:

  • Clean your room
  • Close the door
  • Take out the trash

The title of your subject line should fit into the following phrase:

“If this PR is merged it will “

eg:

Add a new home screen
“if this PR is merged it will” add a new home screen.

Answer the following questions:

  1. Why is this change necessary?
    This question tells reviewers of your pull request what to expect in the commit, allowing them to more easily identify and point out unrelated changes.
  2. How does it address the issue?
    Describe, at a high level, what was done to affect change.Introduce a red/black tree to increase search speed orRemove [troublesome gem X], which was causing [specific description of issue introduced by gem]are good examples. If your change is obvious, you may be able to omit addressing this question.
  3. What side effects does this change have?
    This is the most important question to answer, as it can point out problems where you are making too many changes in one commit or branch. One or two bullet points for related changes may be okay, but five or six are likely indicators of a commit that is doing too many things. Your team should have guidelines and rules-of-thumb for how much can be done in a single commit/branch.

Contribution guidelines

Using Gerrit

OK, first assumption: You were sent a whatsapp that gave you a unique password, to access the gerrit review interface. There you would have been prompted to give your SSH public key. Do this, for git cloning purposes. If you are uncertain, you may skip this step, and just use http for cloning instead.

If you do not want use ssh, that is fine. Then, after loggin in, click the drop down arrow below your name in the Gerrit GUI interface, and go to settings. From there, go to the HTTP Password tab on the left hand side. Click "Generate Password. Copy that password that gets displayed.

I also assume that you would have cloned the repo by now. The command was:

$ git clone ssh://<username>@www.codebreakers.co.za:29418/codebreakers

or

$ git clone http://www.codebreakers.co.za:8080/p/codebreakers
  Cloning into 'codebreakers'...
  Username for 'http://www.codebreakers.co.za:8080': $<username>
  Password for 'http://<username>@www.codebreakers.co.za:8080':

where <username> is your username on gerrit, and incidentally, also your google username. The password is the one generated in the user settings.

An ssh example would be

$ git clone ssh://heymann.murray@www.codebreakers.co.za:29418/codebreakers

It is vital that you have registered and added your ssh public key, otherwise, cloning will simply not work.

Now, a quick summary on how to make make and send changes (patches) for review:

You will of course only have to clone once. Unless you delete the entire project directory, you should not have to do so again.

Whenever you start new work on your game level, no matter how small, always checkout the master branch and pull (from a clean working directory). This ensures that you are on the latest version and minimizes potential merge conflicts in git.

$ git checkout master
$ git pull origin

Then create and checkout a branch, naming it somewhat descriptively.

$ git checkout -b my_branch

Note the -b flag, that tells git to actually create this branch.
Do your coding, committing regularly. Once you are ready to submit for review, you need to first rebase and squash all your commits together in a single review commit. Take note that the review commit is again in a newly created branch. The branch is created while my_branch is checked out, so it also contains all the latest changes at this point

$ git checkout -b my_branch_review

Next, the rebasing and squashing, done with the --interactive flag

$ git rebase master --interactive

Alternatively, these two steps may be replaced with

$ git checkout -b my_branch_review
$ git reset --soft origin/master
$ git commit -m "A single commit message"

The interactive rebase will run your preferred text editor according to git, for which I strongly recommend vim. Generally, the top line can be kept as "pick", and the rest changed to f or s. When you are done, save and quit.

Once the rebasing and squashing is done, the commit can be pushed to the server for review:

$ git push origin my_branch_review:refs/for/master

In the GUI environment online for gerrit, set someone to review your code.

Suppose your patch has some issue, that a reviewer points out that needs fixing first. If you still have the you commited, you may simply just check it out. If not, you need to fetch it.

First, ls all the commits on gerrit for the project with

$ git ls-remote
  From ssh://heymann.murray@www.codebreakers.co.za:29418/codebreakers.git
  d5a54cc7a7b889a2052ed9dc92dc82a62e0f6591	HEAD
  44f45cb46d84f1f7c2e0028a8d7f03af360bb88a	refs/changes/18/18/1
  .
  .
  .

The pactch you are interested will be amongst the ones of the form "refs/changes/*/*/*". Note, the numbers in the places of the asterisk will correspond to the number in the browser url when viewing the commit in the browser GUI interface.

Once the commit has been identified, fetch it and check it. Say you want to view the "refs/changes/18/18/1" patch:

$ git fetch origin refs/changes/18/18/1 && git checkout -b some_branch_name FETCH_HEAD

Now, you will have a new branch with the name you provided, in this example, "some_branch_name", with the patch in question. You make the changes needed, stage them again with "git add" and then commit them with "git commit --amend". Lastly, the new patch is commited to Gerrit

$ git add -u
$ git commit --amend -C HEAD
$ git push origin HEAD:refs/for/master

The "-C HEAD" flags tells git to use the same commit message again.

Hosting

For now, all testing can easily done by a node.js script.

Install:

$ sudo apt-get install nodejs npm
$ sudo npm install express
$ sudo npm install http-server -g
$ sudo npm install -g yo generator-phaser-official

Run the server locally using:

nodejs src/SimpleServer.js server

or

http-server src/server
					

TODO:

  • Basically everything

General Comments

Don't judge the very simple csv. It was hastily crafted over Christmas.

Who do I talk to?

  • Murray Heymann, heymann dot murray at gmail.com