gala/HACKING

====== 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.

    https://github.com/elementary/gala/issues

Help getting Gala translated in your language!

    https://l10n.elementary.io/projects/desktop/gala/

Answer questions.

    https://elementaryos.stackexchange.com/questions/tagged/gala

====== Check out the sources ======

    git clone https://github.com/elementary/gala.git

The development trunk (master, tip) is the latest iteration of the next
release. Browse it online and look for other branches at:

    https://github.com/elementary/gala

====== Build the code ======

Prepare the source and compile:
    meson --prefix=/usr build
    ninja -C build
    sudo ninja -C build install

Run Gala:
    ./build/src/gala --replace

For more detailed instructions, please see the INSTALL file.

===== 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 K&R "One True Brace Style" (1TBS),
with a caveat: spaces are inserted before opening parenthesis.

For indenting the source code only tabs are used!
Tabs should be 4 spaces wide for code to look good.

Consider the following snippet as an example:

    int test_check ()
    {
        if (x < 0) {
            message ("Negative");
            negative (x);
        } else {
            message ("Non-negative");
            nonnegative (x);
        }
        
        return 0;
    }

Of course the best example is the current source code itself.

You can also have a look at this doc for some parts:

   https://elementary.io/docs/code/reference#code-style

Keep in mind that neither the indentation rules or curly
bracket positions mentioned there apply for Gala.

====== Committing code ======

On Github, you should fork the Gala repo and then clone your fork.

Make a branch which will contain your changes for fixing bug 123456:

    git branch fix-123456
    git checkout fix-123456

Tell Git your name and email if you haven't yet:

    git config --global user.name "Real Name"
    git config --global user.email email@address

See what you did so far:

    git diff

Get an overview of changed and new files:

    git status

Add new files, move/ rename or delete:

    git add FILENAME
    git mv OLDFILENAME NEWFILENAME
    git rm FILENAME

Note: 'git add' should be used when a file has been changed to add it to the commit.

After making your changes, you need to commit your work as a new revision.

    git commit

Git will open the default text editor (in most systems, nano) where you
will write the commit message, save the document, and close it. Git will
use the commit message as commentary for the new revision, so it should be
a concise summary of what you did.

To change Git's text editor:

    git config --global core.editor your_text_editor_here
    
For example:

    git config --global core.editor emacs

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:

    git log -5

In the case you added something wrong or want to ammend it:

    git reset HEAD file

If you want to revert all the changes made after the last revision:

    git checkout -- *

Remember to keep your branch updated:

    git remote add upstream https://github.com/elementary/gala.git
    git fetch upstream
    git pull upstream master

As a general rule of thumb, 'man git COMMAND' gives you an explanation of any
command and 'git help' lists all available commands.

====== Push proposed changes ======

After you have commited your patch(es), just push it to your fork
on Github and you can propose it for merging into master by creating a pull request. This will
automatically request a review from other developers who can then comment on
it and provide feedback.

    git push --set-upstream origin fix-123456

If a commit fixes a reported bug on Github, it is useful to make a
reference to that bug report in the pull request

On Github, you will be able to propose it for merging into master.
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 will be removed after they
have been merged.

For larger feature branches, you can add collaborators on Github 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?

Similarly to with master you can create pull requests to other branches on Github,
if the pull request is from a fork you will have to clone that fork first however.

Updating a branch that may be out of sync with trunk:

    git pull
    git: Automatic merge failed; fix conflicts and then commit the result.
    # Hand-edit conflicting changes
    git add FILENAME
    # If any conflicts remain continue fixing
    git commit -m 'Merge master into fix-123456'

====== License ======

This document and the Gala project are licensed under the
GPL Version 3.