Developer Guide

Introduction

This will serve as a guide for the Halalan development model and workflow.

For developers who are new to Git, I strongly suggest that you read the Pro Git Book first. But if you're in a hurry and would like to get your feet wet already, you can check out the Git Reference.

Repositories

Halalan currently has three distinct and independent hosted repositories.

default

The default repository is where all the active development goes on. Currently, it has two long-lived branches namely:

1. master
2. develop

The master branch will always contain the latest stable code (currently Halalan 1.6.0 which is the last release for the 1.x.x series). The line of development for Halalan 2.x.x is contained in the develop branch.

wiki

Obviously, this repository contains the wiki pages of the Halalan project. You most probably wouldn't have to deal with this repo unless you want to create and edit wiki pages manually (i.e. using a text editor). This repository also contains the Halalan User Guide and the related images.

up

This repository is basically a clone of the default repository plus some UP-specific changes. It closely follows the development happening in the default repository. That is, every once in a while, commits from the default repository are pulled into this repository and merged. This is the Halalan version which the University of the Philippines uses.

NOTE: Never ever push commits from this repository to the default repo.

Workflow

git-flow will be the reference workflow. It should be followed as much as possible for the team to have a consistent workflow and branching model. Of course, this doesn't mean that the developers can't deviate from it especially for special cases (e.g. branch naming for the 2.0 rewrite--2xx-rewrite).

Tips

Initial config

# Identification
git config --global user.name "Your Name"
git config --global user.email your@email.com
# Tools
git config --global core.editor vim
git config --global merge.tool kdiff3
# Misc
git config --global color.ui true
git config --global merge.log true

The config above sets vim as your editor and kdiff3 as your merge tool. You're free to use whatever tool you like.

Modify last commit

Did you forget to include a file your last commit? Or do you want to improve your commit log? For whatever reason, if you want to redo your last commit, you can easily do so in Git using:

git commit --amend

Restore original state

To restore modified files back to their original state in the last commit, you can do one of the following:

For specific files or directories:

git checkout HEAD -- <paths>...

For the whole repo:

git reset HEAD --hard

WARNING: the reset command is capable of altering history

Branch from a specific reference

git checkout <ref> -b <new branch name>

The command above does two things:

1. Create a new branch pointing to <ref> (e.g. SHA-1 hash, tag)
2. Switch to the new branch

This can be used if you want to fix a bug in an old release.

Optimize repository

Run the following command every 50 or so commits to optimize and re-pack your local repository:

git gc --prune=today --aggressive

Comparing two repositories

git remote add -f b path/to/repo_b.git
git diff master remotes/b/master
git remote rm b