Merge lp:~kalikiana/midori/hacking into lp:midori

[Cris Dywan]

Replace INSTALL/ HACKING with exported Contribute wiki page

Replace INSTALL/ HACKING with exported Contribute wiki page

[Paweł Forysiuk (tuxator)]

Would be awesome if we could strip markup somehow. Mostly <code></code> tags and [[ ]] for links.
I guess italics tag // will be tricky to match. But those two above should go as they go in the way when trying to read the text.

There is no info now about
MIDORI_TOUCHSCREEN MIDORI_EXTENSION_PATH
and G_DEBUG=all
Probably could/should be added to wiki then.

Otherwise looks good.

[Cris Dywan (kalikiana)]

Both MIDORI_TOUCHSCREEN and MIDORI_EXTENSION_PATH are obsolete, you don't need them.

[Cris Dywan (kalikiana)]

I will add something about G_DEBUG=all to the wiki, we can polish that until release and the file will be updated as the script is run.

[Paweł Forysiuk (tuxator)]

review: Approve

=== modified file 'HACKING'
--- HACKING	2011-01-30 20:35:39 +0000
+++ HACKING	2013-05-29 19:40:32 +0000
@@ -1,169 +1,200 @@
-This file is licensed under the terms of the expat license, see the file EXPAT.
-
-+ Hacking guide for Midori +
-
-- How to contribute
-- Coding style
-- Source files in the project
-- Examplary source code
-
-+++ How to contribute +++
-
-There are several ways to contribute to the project:
-
-For translating, have a look at the file TRANSLATE.
-
-For helping with testing and triaging bug reports, you should register with the bug tracker at https://bugs.launchpad.net/midori and join #midori on irc.freenode.net where a lot of problems are discussed. You can start right away by trying to reproduce bug reports and comment with your findings.
-
-If you are interested in contributing code, there are a few options. You can join #midori to discuss a particular problem you would like to look into, or a feature you would want to implement. Opening a bug report or feature request if there isn't already one is the next step. To attract some attention, if you attached a patch or have questions, ask in #midori.
-
-+++ Coding style +++
-
-Indentation is 4 spaces, no tabs, preferrably at 80 to 120 columns per line to
-avoid automated line-breaks. Trailing whitespace is not desirable.
-
-Declarations go to the beginning of a block, not inline. Variables of one plain
-type may be grouped in one declaration, pointer types may not be grouped. The
-asterisk goes next to the type.
-Variables should be ordered in the order they are used.
-
-Comments explain functionality, they should not state facts. The appropriate
-style is always C style /* */, not C++ style.
-
-Variable and function names should be animal, animal_shelter or animalsc in
-case it would otherwise be very long. Loop counters may be single letters.
-Type names should be Animal, AnimalShelter or AnimalSC. No prefixes from third
-party projects should be used, such as GTK or WebKit, while underlines may be
-used but do not have a particular meaning.
-
-There is a space between functions or keywords and round brackets, and curly
-brackets always go on separate lines, at the indentation level of the
-function, conditional or loop expression. Curly brackets are left out for single
-statement conditionals and loops unless they notably help readability.
-The type of a function goes on a separate line before the function.
-Preprocessor instructions are indented with the code they relate to.
-
-Code history is precious, so one should avoid renaming a lot of functions at
-once or moving whole paragraphs only to add or remove a level of indentation.
-Moving blocks of code around is also undesriable because it makes patches less
-readable since the result looks like new code.
-
-
-+++ Source files in the project +++
-
-Core:
-    Files prefixed with "midori-" in the folder "midori" make up the core. They
-    are essential to running the browser and mostly tailored to the browser.
-    All header files prefixed with "midori-" are considered supported API and
-    can be used to implement extensions.
-    "sokoke" is a collection of very specialized helper functions which change
-    from time to time as needed. In the past some of the code was moved to
-    "katze" when it was considered generally useful.
-    "socket" is a socket implementation with no dependency on other parts of
-    the core, which is used if Midori is built without an external single
-    instance support library.
-Panels:
-    Files in the "panels" folder are classes that implement MidoriViewable and
-    which are loaded into the MidoriPanel at startup. These panels are in
-    principle optional.
-Katze:
-    Re-usable classes and utility functions that don't depend on the core and
-    some of that code indeed found its way into other projects.
-Extensions:
-    These are extensions, written in C, which are loaded optionally if the user
-    so chooses. Extensions can use API from "midori-" and "katze-" headers. Each
-    module consists of either a single .c file or a folder with .c files.
-Tests:
-    Unit tests are run regularly to verify possible regressions or measure
-    performance of implementations. Except for select cases code changes should
-    not cause failure of unit tests.
-
-
-+++ Examplary source code +++
-
-    /*
-       Copyright
-       LICENSE TEXT
-    */
-
-    #include "foo.h"
-
-    #include "bar.h"
-
-    #include <glib.h>
-
-    void
-    foobar (FooEnum bar, const gchar* foo)
-    {
-        gint n, i;
-
-        if (!foo)
-            return;
-
-        #ifdef BAR_STRICT
-        if (bar == FOO_N)
-        {
-            g_print ("illegal value for 'bar'.\n");
-            return;
-        }
-        #endif
-
-        /* this is an example */
-        switch (bar)
-        {
-        case FOO_FOO:
-            n = bar + 1;
-            break;
-        case FOO_BAR:
-            n = bar + 10;
-            break;
-        default:
-            n = 1;
-        }
-
-        for (i = 0; i < n; i++)
-        {
-            g_print ("%s\n", foo);
-        }
-    }
-
-Header file example:
-
-    /*
-       Copyright
-       LICENSE TEXT
-    */
-
-    #ifndef __FOO_H__
-    #define __FOO_H__ 1
-
-    #ifdef HAVE_BAR_H
-        #define BAR_STRICT
-    #endif
-
-    /* Types */
-
-    typedef enum
-    {
-        FOO_FOO,
-        FOO_BAR,
-        FOO_N
-    } FooEnum;
-
-    typedef struct
-    {
-        FooEnum foo_bar;
-    } FooStruct;
-
-    /* Declarations */
-
-    void
-    foo_bar           (FooEnum      bar,
-                       const gchar* foo);
-
-    const gchar*
-    foo_foo           (FooStruct foo_struct,
-                       guint     number,
-                       gboolean  flag);
-
-    #endif /* !__FOO_H__ */
+====== Midori - Contribute ======
+
+**This document is licensed under the LGPL 2.1.**
+
+====== Check out the sources ======
+
+bzr branch lp:midori
+
+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/midori or http://bazaar.launchpad.net/~midori/midori/trunk/tarball download a tarball of the latest revision.
+
+//The code used to be hosted in git.xfce.org/apps/midori.//
+====== Join IRC chat rooms ======
+
+Join irc://irc.freenode.net/midori #midori on Freenode https://kiwiirc.com/client/irc.freenode.net/midori or use webchat to talk about Midori, discuss bugs and new ideas.
+====== Contribute other than touching code ======
+
+  * http://bugs.launchpad.net/midori Go through problem reports and check Unconfirmed bugs or those lacking information and mark any duplicates you spot
+  * https://www.bountysource.com/#trackers/130181-midori Add a bounty for a feature or bug you'd like to support
+
+====== Build the code ======
+
+./waf configure --prefix=/usr
+./waf build
+sudo ./waf install
+
+Midori can be **run without being installed**.
+
+_build/default/midori/midori
+
+You can use a **temporary folder for testing** without affecting normal settings
+
+_build/default/midori/midori -c /tmp/midoridev
+
+You'll want to **unit test** the code if you're testing a new version or contributed your own changes:
+
+xvfb-run ./waf check
+
+Automated daily builds in Launchpad (https://launchpad.net/~elementary-os/+archive/daily ppa:elementary-os/daily and https://launchpad.net/~midori/+archive/midori-dev ppa:midori/midori-dev) run these tests as well.
+====== Debugging issues ======
+
+Testing an installed release may reveal crashers or memory corruption which require investigating from a local build and obtaining a stacktrace (backtrace, crash log).
+
+_build/default/midori/midori -g [OPTIONAL ARGUMENTS]
+
+For more specific debugging output, depending on the feature in question you may use
+
+env MIDORI_DEBUG=help _build/default/midori/midori
+
+====== Coding style and quality ======
+
+Midori code should in general have:
+
+  * 4 space indentation, no tabs
+  * Between 80 to 120 columns
+  * Prefer /* */ style comments
+  * Call variables //animal// and //animal_shelter// instead of <del>camelCase</del>
+  * Keep a space between functions/ keywords and round parentheses
+
+For Vala:
+
+  * Prefer //new Gtk.Widget ()// over //using Gtk; new Widget ()//
+  * Stick to standard Vala-style curly parentheses on the same line
+  * Cuddled //} else {// and //} catch (Error error) {//
+
+For C:
+
+  * Always keep { and } on their own line
+
+//Extensions may historically diverge from the standard styling on a case-by-case basis//
+
+====== Committing code ======
+
+Tell Bazaar your name if you haven't yet
+    bzr whoami "Real Name <email@address>"
+
+See what you did so far
+    bzr diff
+
+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
+
+Commit all current changes - Bazaar automatically picks up edited files. //If you're used to git, think of an implicit staging area.//
+    bzr commit -p
+
+If you've done several commits
+    bzr log | less
+    bzr log -p | less
+
+In the case you committed something wrong or want to ammend it:
+    bzr uncommit
+
+If you end up with unrelated debugging code or other patches in the current changes, it's sometimes handy to temporarily clean up. //This may be seen as bzr's version of git stash.//
+    bzr shelve
+    bzr commit -p
+    bzr unshelve
+
+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.
+
+//If you're a die-hard git user, http://zyga.github.io/git-lp/ checkout git-lp to use git commands with the Bazaar repository.//
+
+====== 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 --remember lp:~USERNAME/midori/fix-bug1120383 && bzr lp-propose-merge lp:midori
+
+lp-propose-merge command may not be working on some distributions like Arch or Fedora.
+In case you get error like //bzr: ERROR: Unable to import library "launchpadlib": No module named launchpadlib// just use Launchpad's Web UI to propose a merge.
+
+
+**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.
+
+bzr push --remember lp:~midori/midori/featuritis && bzr lp-propose-merge lp:midori
+
+What if I want to help out on an **existing merge request** that I can't push to?
+
+
+bzr branch ~OTHERPERSON/midori/fix-bug1120383
+cd fix-bug1120383
+# make commits
+bzr push lp:USERNAME~/midori/fix-bug1120383
+bzr lp-propose-merge ~OTHERPERSON/midori/fix-bug1120383
+
+
+Updating a branch that may be out of sync with trunk:
+
+
+bzr pull
+bzr: ERROR: These branches have diverged
+bzr merge lp:midori
+# Hand-edit conflicting changes
+bzr resolve FILENAME
+# If any conflicts remain continue fixing
+bzr commit -m 'Merge lp:midori'
+
+
+Save a little bandwidth, **branch from an existing local copy** that you keep around:
+
+
+bzr branch lp:midori midori
+bzr branch midori midori.fix-bug1120383
+cd midori.fix-bug1120383
+bzr pull lp:midori
+
+====== Midori for Windows ======
+===== Dependencies =====
+Midori for Windows is compiled on a Linux host and MinGW stack. For the current build Fedora 18 packages are used. Packages needed are listed below:
+
+yum install gcc vala intltool
+
+For a native build
+yum install libsoup-devel webkitgtk3-devel sqlite-devel
+
+For cross-compilation
+yum install mingw{32,64}-webkitgtk3 mingw{32,64}-glib-networking mingw{32,64}-gdb
+
+Packages needed when assembling the archive
+ yum install faenza-icon-theme p7zip mingw32-nsis
+
+Installing those should get you the packages needed to successfully build and develop Midori for Win32.
+
+===== Building =====
+For 32-bit builds:
+
+mingw32-env
+./configure --enable-gtk3 --prefix=/usr/i686-w64-mingw32/sys-root/mingw/
+make
+sudo make install
+
+For 64-bit builds:
+
+mingw64-env
+./configure --enable-gtk3 --prefix=/usr/x86_64-w64-mingw32/sys-root/mingw/
+make
+sudo make install
+
+Once built and tested you can assemble the Midori archive with a helper script
+32-bit build:
+env MINGW_PREFIX="/usr/i686-w64-mingw32/sys-root/mingw" ./win32/makedist/makedist.midori
+64-bit build:
+env MINGW_PREFIX="/usr/x86_64-w64-mingw32/sys-root/mingw/" ./win32/makedist/makedist.midori x64
+
+===== Testing =====
+For testing your changes unfortuantely a real system is needed because Midori and WebKitGTK+ don't work properly under Wine. Even if it works some problems are not visible when using Wine, but are present when running under a real Windows system and vice versa.
+
+One way around it is to virtualize Windows on a Linux host and mount your MinGW directories as a network drive or shared folder.
 \ No newline at end of file
 
=== removed file 'INSTALL'
--- INSTALL	2012-11-26 18:05:35 +0000
+++ INSTALL	1970-01-01 00:00:00 +0000
@@ -1,82 +0,0 @@
-This file is licensed under the terms of the expat license, see the file EXPAT.
-
-+++ Installing Midori +++
-
-Building and installing Midori is straightforward.
-
-Make sure you have Python 2.4 or higher installed.
-
-Change to the Midori folder on your hard disk in a terminal.
-
-Run './waf configure'
-
-Run './waf build'
-
-You can now run Midori from the build folder like so
-
-'_build/default/midori/midori'
-
-Midori will pick up extensions and resources from the build folder;
-it will NOT use localizations.
-
-You can install it with './waf install'
-
-If you need to do a clean rebuild, you can do either './waf clean'
-in order to remove binaries or './waf distclean' which deletes generated
-configuration files as well.
-
-For further options run './waf --help'
-
-+++ Debugging Midori +++
-
-Midori is by default built with debugging symbols, make sure you have
-installed 'gdb', the GNU Debugger.
-
-It's a good idea to execute all unit test cases and see that they pass.
-
-'xvfb-run ./waf check'
-
-In this example, Xvfb is used to avoid relying on the local user setup.
-
-You can also run Midori proper as 'gdb _build/default/midori/midori'.
-
-Inside gdb, type 'run'.
-
-Try to reproduce a crash that you experienced earlier,
-this time Midori will freeze at the point of the crash.
-Switch to your terminal, type bt ('backtrace') and hit Return.
-What you obtained now is a backtrace that should include
-function names and line numbers.
-
-If the problem is a warning and not a crash, try this:
-
-'G_DEBUG=all gdb _build/default/midori/midori'
-
-If you are interested in HTTP communication, try this:
-
-'MIDORI_DEBUG=headers _build/default/midori/midori'
-
-Where 'headers' can be replaced with 'body' to get full message contents.
-
-If you are interested in (non-) touchscreen behaviour, try this:
-
-'MIDORI_TOUCHSCREEN=1 _build/default/midori/midori', or
-
-'MIDORI_TOUCHSCREEN=0 _build/default/midori/midori'
-
-If you want to "dry run" without WebKitGTK+ rendering, try this:
-
-'MIDORI_DEBUG=unarmed _build/default/midori/midori'
-
-If you want to test bookmarks, you can enable database tracing:
-
-'MIDORI_DEBUG=bookmarks _build/default/midori/midori'
-
-To disable Netscape plugins, use MOZ_PLUGIN_PATH=/.
-
-When running from the build folder, extensions will also be located
-in the build folder (setting MIDORI_EXTENSION_PATH is no longer needed).
-
-For further information a tutorial for gdb and
-reading up on how you can install debugging
-symbols for libraries used by Midori are recommended.
 
=== modified file 'tools/release'
--- tools/release	2013-05-19 14:04:16 +0000
+++ tools/release	2013-05-29 19:40:32 +0000
@@ -16,6 +16,9 @@
     OLDVER=0.5.1
     sed -i "s@$OLDVER@$NEWVER@g" wscript win32/makedist/midori.nsi
     echo; echo v$NEWVER:; bzr log --line -rtag:$OLDVER.. | sed -r 's@.+2013-[0-9]+-[0-9]+ @@' | grep -v l10n | grep -v makedist | grep -v tools/release | grep -v nsi | grep -v -E 'Update .+ translation'; echo
+    curl http://wiki.xfce.org/_export/raw/midori/contribute | \
+        sed -r 's@\[\[([^|]+)\|([^]]+)\]\]@\1 \2@g' | \
+        sed -r 's@<code( bash|)>|</code>@@g' > HACKING
     curl http://wiki.xfce.org/_export/xhtml/midori/faq | \
         sed 's@This is a list of frequently asked questions@This is <a href="http://wiki.xfce.org/midori/faq">a snapshot of the online FAQ</a>@g' | \
         sed 's@<link rel="style.*>@<link rel="stylesheet" href="faq.css" />@g' > data/faq.html