Merge lp:~elementary-apps/pantheon-terminal/hacking-doc into lp:~elementary-apps/pantheon-terminal/trunk

[David Gomes]

Added a HACKING document.

Added an HACKING file.

[Akshay Shekher (voldyman)]

Fixy line 10 rest is good.

review: Needs Fixing

[lp:~elementary-apps/pantheon-terminal/hacking-doc]

514. By David Gomes on 2013-08-30

Fixed PPA link.

[Akshay Shekher (voldyman)]

Looks good.

review: Approve

=== added file 'HACKING'
--- HACKING	1970-01-01 00:00:00 +0000
+++ HACKING	2013-08-30 12:58:30 +0000
@@ -0,0 +1,222 @@
+====== Pantheon Terminal - Contribute ======
+
+====== Testing the latest build ======
+
+Get daily builds on Launchpad for Ubuntu 12.04 and later.
+
+    https://launchpad.net/~elementary-os/+archive/daily
+
+====== Join IRC chat rooms ======
+
+Join #elementary-dev on Freenode (irc.freenode.net).
+
+====== Contribute without touching code ======
+
+Go through problem reports and check unconfirmed bugs or those lacking
+information and mark any duplicates you spot.
+
+    http://bugs.launchpad.net/pantheon-terminal
+
+Help getting Pantheon Terminal translated in your language!
+
+    https://translations.launchpad.net/pantheon-terminal
+
+Answer questions.
+
+    https://answers.launchpad.net/pantheon-terminal
+
+====== Check out the sources ======
+
+    bzr branch lp:pantheon-terminal
+
+The development trunk (master, tip) is the latest iteration of the next
+release. Browse it online and look for other branches at:
+
+    http://code.launchpad.net/pantheon-terminal
+
+====== Build the code ======
+
+Prepare the source and compile:
+    mkdir build
+    cd build/
+    cmake .. -DCMAKE_INSTALL_PREFIX=/usr
+    make
+
+Run Pantheon Terminal:
+    ./pantheon-terminal # from build/
+
+====== Important: Keep fixes for different bugs in different branches ======
+
+Branches that contain patches to fix more than one bug will be rejected, and
+you will be asked to supply a separate branch for every bug fix. However,
+this doesn't apply to patches that are indivisible by nature, and that
+fix multiple bugs.
+
+The reasons to work in this way are the following:
+
+If one of the bugs targeted by your branch is correctly fixed, but one of the
+other bugs is incorrectly fixed or needs corrections, the branch won't be
+accepted until everything looks ok for all bugs. This causes an unnecessary
+delay for the bugs that where fixed correctly.
+
+Suppose your branch was accepted for merging in the main one. Later, it is 
+discovered that your branch introduces faulty behavior. The standard course of
+action for these situations is to revert the merge that introduced that faulty
+behavior. This will cause that all of your fixes are reverted (even the ones
+that didn't cause problems) because there was no way of discriminating between
+them. If a separate branch for each bug fixed existed, only the offending one
+would have been reverted, and not all of them.
+
+Be sure to understand this, and avoid a headache later!
+
+====== Coding style ======
+
+Pantheon Terminal's source code in general follows the elementary Code Style.
+In fact, you can read more about it here:
+
+   http://elementaryos.org/docs/code/code-style
+
+====== Committing code ======
+
+Make a branch which will contain your changes for fixing bug 123456:
+
+    bzr branch lp:pantheon-terminal fix-123456
+
+Tell Bazaar your name if you haven't yet:
+
+    bzr whoami "Real Name <email@address>"
+
+See what you did so far:
+
+    bzr diff
+    bzr diff | less
+
+Get an overview of changed and new files:
+
+    bzr status
+
+Add new files, move/ rename or delete:
+
+    bzr add FILENAME
+    bzr mv OLDFILENAME NEWFILENAME
+    bzr rm FILENAME
+
+Note: 'bzr add' should be used only when new source or data files are added
+to Pantheon Terminal's source directory.
+
+After making your changes, you need to commit your work as a new revision.
+
+    bzr commit
+
+Bazaar will open the default text editor (in most systems, nano) where you
+will write the commit message, save the document, and close it. Bazaar will
+use the commit message as commentary for the new revision, so it should be
+a concise summary of what you did.
+
+To change Bazaar's text editor, add the following line to Bazaar's
+configuration file (usually located at ~/.bazaar/bazaar.conf):
+
+    editor = your_text_editor_here
+    
+For example:
+
+    editor = gedit
+
+Commit your changes in small increments. It is better to keep different
+changes in different commits.
+
+If a commit fixes a reported bug in Launchpad, it is useful to make a
+reference to that bug report when committing:
+
+    bzr commit --fixes lp:123456
+
+Did you make changes to more than one file, but don't want to commit the
+changes of all of them? You can specify which files you want to commit:
+
+    bzr commit file1 file2
+
+To see the last 5 revisions in the current branch:
+
+    bzr log -l5
+    bzr log -l5 -p | less
+
+In the case you committed something wrong or want to ammend it:
+
+    bzr uncommit
+
+If you want to revert all the changes made after the last revision:
+
+    bzr revert
+
+Remember to keep your branch updated:
+
+    bzr pull
+
+As a general rule of thumb, 'bzr help COMMAND' gives you an explanation of any
+command and 'bzr help commands' lists all available commands.
+
+====== Push proposed changes ======
+
+If you haven't yet, https://launchpad.net/~/+editsshkeys check that Launchpad
+has your SSH key - you can create an SSH key with Passwords and Keys aka
+Seahorse or 'ssh-keygen -t rsa' - and use 'bzr launchpad-login' to make
+youself known to bzr locally.
+
+If you checked out trunk, and commited your patch(es), just push it under your
+username in Launchpad and you can propose it for merging into trunk. This will
+automatically request a review from other developers who can then comment on
+it and provide feedback.
+
+    bzr push lp:~USERNAME/pantheon-terminal/fix-123456
+    bzr lp-open
+
+The last command will open a summary of the current branch in your web
+browser. There, you will be able to propose it for merging into trunk.
+Your branch will be reviewed by another developer. At this stage, you may be
+notified that changes need to be made to your branch, so keep an eye on your
+email inbox!
+After the branch is approved by the reviewer, it will get merged into the main
+project's source code.
+
+
+What happens to all the branches?
+
+Leave the branches alone, approved branches are cleared automatically by
+Launchpad.
+
+For larger feature branches, use the team in Launchpad to allow other
+developers to work on the code with you.
+
+What if I want to help out on an existing merge request that I can't push to?
+
+    bzr branch lp:~OTHERPERSON/pantheon-terminal/fix-123456
+    cd fix-123456
+    # make commits
+    bzr push lp:~USERNAME/pantheon-terminal/fix-123456
+    bzr lp-open
+
+And in the Launchpad web overview of your branch, propose your branch for
+merging into lp:~OTHERPERSON/pantheon-terminal/fix-123456
+
+Updating a branch that may be out of sync with trunk:
+
+    bzr pull
+    bzr: ERROR: These branches have diverged
+    bzr merge lp:pantheon-terminal
+    # Hand-edit conflicting changes
+    bzr resolve FILENAME
+    # If any conflicts remain continue fixing
+    bzr commit -m 'Merge changes from lp:pantheon-terminal'
+
+Save a little bandwidth, branch from an existing local copy that you keep
+around:
+
+    bzr branch lp:pantheon-terminal pantheon-terminal
+    bzr branch pantheon-terminal/ pantheon-terminal-fix-123456
+    cd pantheon-terminal-fix-123456
+    bzr pull lp:pantheon-terminal
+
+====== License ======
+
+This document and the Pantheon Terminal project are licensed under the
+GPL Version 3.