From 80afa860d4fe57ab41f87617d46ade4b7fe511d1 Mon Sep 17 00:00:00 2001 From: Tom Beckmann Date: Fri, 30 Aug 2013 15:03:22 +0200 Subject: [PATCH] Add HACKING file based on pantheon-terminal's HACKING file --- HACKING | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 288 insertions(+) create mode 100644 HACKING diff --git a/HACKING b/HACKING new file mode 100644 index 00000000..140ca930 --- /dev/null +++ b/HACKING @@ -0,0 +1,288 @@ +====== Gala 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/gala + +Help getting Pantheon Terminal translated in your language! + + https://translations.launchpad.net/gala + +Answer questions. + + https://answers.launchpad.net/gala + +====== Check out the sources ====== + + bzr branch lp:gala + +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/gala + +====== Build the code ====== + +Prepare the source and compile: + mkdir build + cd build/ + cmake .. -DCMAKE_INSTALL_PREFIX=/usr + make + +Run Pantheon Terminal: + ./gala --replace # from build/ + +===== Debugging Code ====== + +Debugging a window manager is not as easy as debugging any window application. +When the window manager processes crashes, it is stopped by gdb, so all your +windows will get stuck. Instead, run gdb from a different tty by pressing +Ctrl+Alt+F6 for example and executing + + gdb gala + # once inside gdb + run -d :0 --replace + +Now, you can switch back to your X session, which will probably be on tty7, +which would be Ctrl+Alt+F7. You can then get program to crash as you usually +would and switch back to tty6 as above and you have full access to all gdb +features like "bt" for getting a backtrace. See the end of the +"If something goes wrong" section if you have troubles starting gala a second +time from gdb. + +===== If something goes wrong ===== + +If gala crashes, you'll usually find yourself in a pretty bad position, as you +can't give focus to a window anymore by clicking on it, so you can't enter text +either. To get things back running, switch to tty6 by pressing ctrl+alt+f6 and +execute + + gala -d :0 --replace + +which will start gala on display :0, which typically is the display you'll be +running. The "--replace" is most probably not required when gala crashed. +You might experience some weirdnesses if you you try to restart gala again from +a tty. The first launch will usually be somehow ignored. If that's the case, +just hit ctrl+c, and start it again. Now it should be running just fine. + +===== Gala is a mutter plugin? ===== + +Mutter works with plugins, although they are not implemented in the way you +would maybe expect. In fact, you should better only load a single plugin at a +time. This plugin will then be queried by mutter for animating windows or +workspaces and defining a few other things. The plugin also has the oppurtinity +to add arbitrary ClutterActors to the stage or registring handlers for shortcuts. + +===== Adding a new shell component ==== + +Shell components are typically placed in the src/Widgets/ folder. They usually derive +from ClutterActor, so they can be added to the stage the wm runs in directly. Once +you defined your actor, you can go to src/Plugins.vala and add a new instance of it +to the stage in the Plugin's start() method. You can register shortcuts for invoking +your view in that function as well. To get input events on your actor, you'll have to +call plugin.begin_modal(), which puts the stage in a mode where only the custom actors +receive events and the windows are unaccessible. When your view is closed, call +plugin.end_modal() to make the windows accessible again. A last option to have elements +like a panel receive clicks, even when not being in modal mode, is to have a look at the +Utils.set_input_region() method. Currently, you'll have to hack your area into it +manually, it is planned to have automatic areas for actors that request it as well later +on as we need it. + +====== 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 ====== + +Gala'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 + +NOTE: we don't use 4 spaces, but tabs instead. Also the position for curly + brackets for declarations differs from the docs, you place the first one + on a new line: + +class MyClass +{ + public void my_method () + { + } +} + +====== Committing code ====== + +Make a branch which will contain your changes for fixing bug 123456: + + bzr branch lp:gala fix-123456 + +Tell Bazaar your name if you haven't yet: + + bzr whoami "Real Name " + +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 Gala'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/gala/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/gala/fix-123456 + cd fix-123456 + # make commits + bzr push lp:~USERNAME/gala/fix-123456 + bzr lp-open + +And in the Launchpad web overview of your branch, propose your branch for +merging into lp:~OTHERPERSON/gala/fix-123456 + +Updating a branch that may be out of sync with trunk: + + bzr pull + bzr: ERROR: These branches have diverged + bzr merge lp:gala + # Hand-edit conflicting changes + bzr resolve FILENAME + # If any conflicts remain continue fixing + bzr commit -m 'Merge changes from lp:gala' + +Save a little bandwidth, branch from an existing local copy that you keep +around: + + bzr branch lp:gala gala + bzr branch gala/ gala-fix-123456 + cd gala-fix-123456 + bzr pull lp:gala + +====== License ====== + +This document and the Gala project are licensed under the +GPL Version 3.