====== Trying out development versions of Geany ======

**Testing** is a useful way to contribute to Geany.

If you're running Linux, it's easy and safe to try out a development version of Geany without affecting your existing Geany setup. This tutorial will show you how. It assumes that you are more or less familiar with the Unix shell. Familiarity with [[https://git-scm.com/|Git]] will help but is not required.

===== Getting started =====

To begin, you will need the GNU toolchain, Git, and the GTK+ and VTE libraries. You can install them with your system's package manager. This should work for Ubuntu or Debian:

<code>
$ sudo apt install build-essential autoconf automake libtool intltool git libgtk2.0-dev libvte-dev
</code>

**TODO: equivalents for Fedora etc.**

If you've never used Git before, you may need to set it up with your name and email (the values you enter don't matter for this tutorial):

<code>
$ git config --global user.name "Your Name"
$ git config --global user.email your.email@example.com
</code>

It may be convenient to create a dedicated directory for testing Geany. This tutorial will use ''~/geany'':

<code>
$ mkdir ~/geany
$ cd ~/geany/
</code>

The "master" development version of Geany is kept [[https://github.com/geany/geany|on GitHub]]. "Clone" it like this:

<code>
$ git clone https://github.com/geany/geany.git
$ cd geany/
</code>

Run the configuration script:

<code>
$ ./autogen.sh --prefix=$HOME/geany/prefix
</code>

In the above command, the ''%%--prefix%%'' option means that Geany and all its files will be installed under ''~/geany/prefix''. This **will not affect** your system-wide installation of Geany (if any), and **does not require** root privileges (sudo). You can pick any other directory instead of ''~/geany/prefix''.

You are now ready to compile and install Geany from source:

<code>
$ make
$ make install
</code>

This takes a few minutes on a modern desktop computer.

Finally, you can run your fresh copy of Geany:

<code>
$ ~/geany/prefix/bin/geany -c ~/geany/config1
</code>

===== Using your real configuration =====

The ''-c'' option above told Geany to keep all its config in the ''~/geany/config1'' directory. Without a ''-c'' option, Geany uses a default location -- normally ''~/.config/geany''. So, if you have a regular, system-wide installation of Geany, its config is safe and completely independent from the development version.

However, it's very useful to test things with your custom config as well. You can do this by creating a //copy// of that config:

<code>
$ cp -r ~/.config/geany ~/geany/config2
$ ~/geany/prefix/bin/geany -c ~/geany/config2
</code>

In fact, you can create as many config directories as you like, and run an independent instance of Geany for each of them.

===== How to test =====

Check some of your favorite features of Geany -- do they work as expected?

Try working as you would normally. Open a project, try editing code in a meaningful way.

If you discover problems, [[https://github.com/geany/geany/issues/new|submit an issue on GitHub]]. Include the Git revision you're running -- you can see it in Geany's "About" box (//Help// → //About//): ''git >= 0d47e09''. Your versions of GTK+ and GLib may also be important -- you can find them in the first lines of //Help// → //Debug Messages//.

===== Testing a pull request =====

Geany is developed [[https://github.com/geany/geany|on GitHub]], and people propose changes or additions to Geany in the form of [[https://github.com/geany/geany/pulls|pull requests]] (PRs). Sometimes there is a PR that looks good, but needs more testing in various scenarios. This is where you can help.

Browse the [[https://github.com/geany/geany/pulls|list of PRs]] to find one that sounds interesting or useful to you. Check the discussion to see if there are any known problems with it (if there are, testing it may not be very useful until those problems are resolved).

At the top of the PR page, it says something like:

> kugel- wants to merge 5 commits into ''geany:master'' from ''kugel-:better-snippets''

''geany:master'' is the master development tree of Geany -- the one from which releases are cut every few months. ''kugel-'' is the GitHub username of the person who proposed this change, and ''better-snippets'' is the name of their Git branch.

At the bottom of the PR page, it should say:

> This branch has no conflicts with the base branch

(if not, you should probably skip this PR for now).

So, the username is ''kugel-'', the branch is ''better-snippets'', and here is how you can merge it:

<code>
$ cd ~/geany/geany
$ git reset --hard origin/master
$ git pull
$ git remote add kugel- https://github.com/kugel-/geany.git
$ git fetch kugel-
$ git merge -m test kugel-/better-snippets
</code>

Recompile and reinstall with this change:

<code>
$ make
$ make install
</code>

Now you have a version of Geany that's the same as the master version, //but// with that PR merged in as well. Run it like before:

<code>
$ ~/geany/prefix/bin/geany -c ~/geany/config2
</code>

Try out the changes introduced by that PR. If it's a new feature, does it work for you? If it's a change, how does it fit into your workflow? Does it work on the kind of files that you normally edit with Geany?

Finally, leave a comment on the PR page on GitHub:

> I tried running with this PR. I briefly checked X, Y, and Z. Seems to work well. I would suggest S though.

Please note that positive testing results **do not guarantee** that the PR will be merged quickly. The maintainers still need some time to review and decide.

To go back to master:

<code>
$ cd ~/geany/geany
$ git reset --hard origin/master
$ make
$ make install
</code>

===== Plugins =====

**TODO: how to install Geany-Plugins from Git as well**

===== Running on a regular basis =====

It's very useful to try out a development version for 10 minutes. But it's even more useful to run a development version for 2 weeks as your main instance of Geany, if you're comfortable with that. Some problems can only be discovered when you're doing regular work.

**TODO: installing into /usr/local, etc.**