Developers/Getting Started/Working with GIT

From Tine 2.0 - Wiki

< Developers‎ | Getting Started

Tine 2.0 uses GIT to manage its source code. This page shows the basic commands and workflow to get started in developing for Tine 2.0. NOTE This is not an GIT introduction. Please familiarize yourself with GIT using the documentation found on the internet.

Overview

Tine 2.0 developement workflow

Repositories

Tine 2.0 official upstream repository is located at:

http://git.tine20.org/git/tine20

We recommend to use our gerrit repo when developing for Tine 2.0. It is located here:

https://gerrit.tine20.org/tine20/p/tine20.git

Development Cycle

Gerrit Quick Intro

As we use gerrit (https://code.google.com/p/gerrit/) to do our code reviews, it is recommended to read this quick introduction into the gerrit workflow first:

https://gerrit.tine20.org/tine20/Documentation/intro-quick.html

The Android development site has a nice chart of the "Life of a patch":

http://source.android.com/source/life-of-a-patch.html

Get a Working Copy

To checkout a working copy of our codebase just execute following commands on your development system:

cd /webserver/documentroot
git clone -o review https://gerrit.tine20.org/tine20/p/tine20.git
git checkout master

if you are working on a bugfix, you would rather checkout the current stable branch (for example 2013.03) instead of master:

git checkout 2013.03

To update your working copy simply type

git pull

Installing external libraries

Install composer

Beginning with version Collin 2013.10 we removed some libraries from our repository and switched to composer to manage them. This way it is easier for us to keep in sync with the external libraries.

To install composer please execute following commands in your homedirectory:

mkdir composer
test -d bin || mkdir bin
curl -sS https://getcomposer.org/installer | php -- --install-dir=composer
ln -s ../composer/composer.phar bin/composer

If everything went well, you should be able to execute

composer -V

on your command line.

If you encounter any problems, please follow the detailed composer installation instructions at http://getcomposer.org/doc/00-intro.md

Fetching the libraries

Now change into the tine20 directory of your git checkout (for example /webserver/documentroot/tine20) and execute following command:

composer install --prefer-source --no-interaction install

This will download the needed libraries. You have to execute this command later, if some of the external libraries got updated or new libraries got added. If everything went well, there should be a vendor directory now, which contains a bunch of php files.


Install npm

Beginning in June 2016, npm is used for javascript dependency management. To install npm (and nodejs), please follow the instructions at https://www.npmjs.com or better follow https://nodejs.org/en/download/package-manager/ and install a high version (nodejs 6+)


Run the following on your development server to install and update the JS libs:

cd Tinebase/js
npm install #--no-optional on linux/windows
sudo ln -s /usr/bin/nodejs /usr/bin/node

Version 6.x (LTS "Boron") of nodejs/npm should be used. Older version might be problematic.

Install webpack

Beginning in June 2016, webpack (webpack.github.io) is mandatory to run your development installation. To start the webpack-dev-server run the following commands:

cd Tinebase/js
./node_modules/webpack-dev-server/bin/webpack-dev-server.js --progress --watch --inline -d

If your dev host is different from localhost (e.g. a virtual machine) you need to add the interface webpack-dev-server should bind to (0.0.0.0 binds to all):

 --host 0.0.0.0

If you use ssl, you need to to add your cert and key files:

 --https --cert <your.cert.file> --key <your.key.file>

If your Filesystem doesn't support events (vagrantfs/nfs) --watch won't work. Use:

 --watch-poll

If you don't want to develop javascript, you can speed up webpack-dev-server by leaving out development mode (-d) and dynamic reloads (--inline) and fs watching (--watch)

IMPORTANT: Starting end of 2016 webpack-dev-server is configured to act as a proxy for the application services (aka web server with PHP). Therefore you need to access your dev instance via the webpack-dev-server on port 10443:

 https://<yourdevurl>:10443/

For debugging webpack-dev-server the internal url might be useful:

 https://<yourdevurl>:10443/webpack-dev-server

Some more information to bind address and start/stop of webpack (from Johannes, see forum post here: https://www.tine20.org/forum/viewtopic.php?f=4&t=18072&p=64836#p64812):

Start Developing

Developing bug fixes or changes is always done in separate branches. Each issue should be managed in a separate branch. Be careful to avoid dependencies of your changes as those can't be reviewed as long as the parent commits aren't merged into the upstream repository.

Start your work with

git checkout -b mylovelyfeature

Now do your work and commit your changes in reasonable steps

git add newfile
git add changedfile
git commit

Enter the commit message, do not forget to add the Change-ID. A good commit message looks like this (see http://stackoverflow.com/a/15324949/2417221 for more about commit messages best practice):


#9058: show query filter when selecting TA foreign filter


- is_open is not longer required as default filter
- maybe we should allow multiple default filters
- adds some logging


https://forge.tine20.org/mantisbt/view.php?id=9058


Change-Id: Ia339d5c96556efeb08f39787058f79cf1378710c


You can download a commit hook from here that automatically includes the change ID in your commit message:


curl -o .git/hooks/commit-msg "https://gerrit.tine20.org/tine20/tools/hooks/commit-msg" && chmod +x .git/hooks/commit-msg


Often the upstream evolves during your work on your developments. Rebase your changes on top of the current upstream.

git checkout master #feature // if bugfix use -> git checkout _STABLEBRANCH_
git pull
git checkout mylovelyfeature
git rebase master #feature //if bugfix use -> git rebase _STABLEBRANCH_

Run Unittests

Before you push your changes or to test a new environment, you might want to run the PHP unit test suite. This is how it's done:

 cd /your/tine20/dir
 vendor/bin/phing -logger phing.listener.DefaultLogger -Dconfigdir=/etc/tine20 phpunit-prepare phpunit-exec

you need a login user for the tests. it can be defined in the config.inc.php:

 'login' =>
   array (
       'username' => 'user',
       'password' => 'pass',
 ),

Push your Changes

Once you are registered as a Tine 2.0 developer, you can push your changes into our code review system. If your changes get accepted they become part of the official Tine 2.0 upstream codebase.

NOTE: in gerrit you need to set your username and password for the GIT repository in your preferences yourself! You get your login to push to git here: https://gerrit.tine20.org/tine20/#/settings/http-password

It is recommended to put the credentials into your ~/.netrc file (if you are a Linux/OSX user) and like to use git on the shell. You need to add a line like this:

machine gerrit.tine20.org login yourusername password *****

The review repository is physically different from the upstream repository. You need to include it as a remote once if you cloned from the official repo:

git remote add review https://gerrit.tine20.org/tine20/p/tine20.git

Before you push, clean up your local history. Each commit you make opens a separate change request. Squash commits if reasonable. Also make sure your changes are rebased on the current upstream master (or _STABLEBRANCH_). Push your (new feature) changes with

git push review HEAD:refs/for/master

Bugfix changes should be pushed to the current stable branch (i.e. 2013.03):

git push review HEAD:refs/for/2013.03

Review Process

You can find your change request in the gerrit web frontend

https://gerrit.tine20.org/tine20/#/q/is:starred,n,z

Your changes are automatically verified in our build system. Once your changes are verified, one ore more of the core developers will review your code manually and give feedback. If your changes are acceptable they get integrated into our upstream repository. Otherwise you will be asked to rework your changes and resubmit them.

Please add the bugtracker ID to the commit message if there is one.

Switch to your feature branch and rework changes as requested

git checkout mylovelyfeature

To resubmit your changes its IMPORTANT to AMEND your previous commit with the new one, and INCLUDE CHANGE-ID in your commit message. The change-id can be found when you open your change in the gerrit web frontend.

git commit --amend 

make sure to include the change-id at the end of your commit message.

Push your revised changes:

git push review HEAD:refs/for/master

or

git push review HEAD:refs/for/2013.03