Merge lp:~junrrein/granite/developer-documentation into lp:~elementary-pantheon/granite/granite

[Julián Unrrein]

Add developer documentation.

Add developer documentation about how to contribute to Granite.

[lp:~junrrein/granite/developer-documentation]

608. By Julián Unrrein on 2013-08-17

Include option to generate debug symbols in configuration step.

[David Gomes (davidgomes)]

Claimed the review, I got this for tomorrow.

[xapantu (xapantu)]

That would be better if it was a normal markdown file, but still, that's an improvement. Thanks :)

review: Approve

=== added file 'HACKING'
--- HACKING	1970-01-01 00:00:00 +0000
+++ HACKING	2013-08-17 21:42:16 +0000
@@ -0,0 +1,143 @@
+====== Granite - Contribute ======
+
+This document is licensed under the LGPL 2.1.
+
+====== Testing the latest build ======
+
+Get daily builds in Launchpad (https://launchpad.net/~elementary-os/+archive/daily ppa:elementary-os/daily).
+
+====== Join IRC chat rooms ======
+
+Join #elementary-dev on Freenode: https://kiwiirc.com/client/irc.freenode.net/elementary-dev.
+
+====== Contribute without touching code ======
+
+- http://bugs.launchpad.net/granite Go through problem reports and check Unconfirmed bugs or those lacking information and mark any duplicates you spot.
+- https://translations.launchpad.net/granite Help getting Granite translated in your language!
+
+====== Check out the sources ======
+
+    bzr branch lp:granite
+
+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/granite
+
+====== Build the code ======
+
+    mkdir build
+    cd build
+    cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug ..
+    make
+
+Run a program using your compiled Granite branch:
+    LD_LIBRARY_PATH=/home/USERNAME/granite/build/lib program
+
+To compile a program using your compiled Granite branch, you will need to install it:
+    sudo make install
+
+====== Coding style and quality ======
+
+Check the official elementary Code Style guide at:
+    http://elementaryos.org/docs/code/code-style
+
+====== 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.
+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!
+
+====== Committing code ======
+
+Make a branch which will contain your changes for fixing bug XXXX:
+    bzr branch lp:granite fix-XXXX
+
+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 | colordiff
+
+Get an overview of changed and new files:
+    bzr status
+
+Add new files, move/ rename or delete:
+    bzr add FILENAME
+    bzr mv OLDFILE NEWFILE
+    bzr rm FILENAME
+
+After making your changes, you need to commit your work as a new revision.
+    bzr commit -m "Commit message"
+
+Commit your changes in small increments. It is better to keep different changes in different commits.
+
+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 added 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/granite/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 ~OTHERPERSON/granite/fix-123456
+    cd fix-123456
+    # make commits
+    bzr push lp:USERNAME~/midori/fix-123456
+    bzr lp-open
+
+And in the Launchpad web overview of your branch, propose your branch for merging into ~OTHERPERSON/granite/fix-123456
+
+
+Updating a branch that may be out of sync with trunk:
+
+    bzr pull
+    bzr: ERROR: These branches have diverged
+    bzr merge lp:granite
+    # Hand-edit conflicting changes
+    bzr resolve FILENAME
+    # If any conflicts remain continue fixing
+    bzr commit -m 'Merge changes from lp:granite'
+
+
+Save a little bandwidth, branch from an existing local copy that you keep around:
+
+    bzr branch lp:granite granite
+    bzr branch granite/ granite-fix-123456
+    cd granite-fix-123456
+    bzr pull lp:granite