DevelopmentHowTo

From Sit
Jump to: navigation, search

Contents

Essential Reading

Getting Started with SiT Development

Outdated icon32.png The information in this article (or section) is out of date needs updating.
Please help us and our readers by clicking the edit link above and updating/improving this text.
Warning Warning:   We've moved to Github (https://github.com/sitracker)

Git / Getting the latest source code

We're using Git (hosted by gitorious.org) as a version control system for v3.90 and beyond.

You can make your own Git clone like this:

git clone git://gitorious.org/sit/sit.git

Subversion / Getting legacy source code

Our legacy branch of SiT! (v3.6x) is in Subversion.

To checkout the SiT subversion (svn) source code tree.

svn co https://svn.code.sf.net/p/sitracker/code/branches/3.x/ sitracker 

Always make sure your source tree is up to date before making changes because you might find the file you're working on has changed in the mean-time if you're not careful, talking to other developers on IRC and watching commit notifications can help with this.

You can also browse the SVN tree via a web interface.

If you are new to subversion you may find the free book Version Control with Subversion useful.

Getting help / Chatting with other developers

Join us in our IRC Channel, there's usually at least one other developer online and you can see commits that other developers make in real time (via the CIA bot), and also bug and wiki news via sitbot.

Creating a patch

Creating a patch is very easy, just checkout the latest code from svn (or update your existing working copy), make your changes then run svn diff > ~/my_patch.diff or you can also run

diff -rup original_file.php my_version_file.php > my_patch.diff

Submitting patches

You can attach a patch to a report in our bug tracker or email your patch to the sitracker-devel-discuss mailing list, or if you have commit access you can submit it directly.

SiT! is a free and open source software project under the GNU GPL v2 and by submitting your contribution you agree to license it under the GNU General Public License v2.

Getting commit access

First submit at least one patch the long way (see above) and have it accepted by our developers, then simply ask on IRC or the devel-discuss mailing list, you'll need to provide a sourceforge (and/or Gitorious.org username), so if you haven't got one already you should sign up with sourceforge and/or Gitorious first.

We may remove your commit access if you do not make a commit for two years, but you can ask for it back.

Finding things to do

There's always lots that needs doing, you can go through the list on our bug tracker if you're short of ideas. If you want to hack on something specific, just let people know, so that they don't start hacking on the same thing, and so that they can discuss it with you. Our Roadmap page details our plans for the future and should give you an idea of where we're aiming for next.

If you don't have any specific ideas, just ask if people need help with something.

Planning changes and new features

We use the Roadmap page to coordinate and make plans for future releases, and we use the sitracker-devel-discuss mailing list or more frequently the IRC channel to discuss it.

Debugging

Configure SiT's Debug Logging and any trigger_error() or php errors will be logged.

SiT Architecture

Broom icon32.png This is a draft article (or section) and is a work-in-progress.
Please help us and our readers by clicking the edit link above and expanding/improving this text.
Info.png Info: This section has been updated to show important changes for 3.45 and later

This is in no way going to be comprehensive, but this section will try and give you an overview of how SiT works from a developer perspective.

Every page that the user accesses is kept under the /htdocs directory or a subdirectory of that. Those pages include more code that is in the /includes directory. With me so far? Good. :-)

A standard page template goes something like this:

<?php
$permission = 0;

require ('core.php');
require (APPLICATION_LIBPATH . 'functions.inc.php');

// This page requires authentication
require (APPLICATION_LIBPATH . 'auth.inc.php');

$title = $strAddContract;

// External variables
$id = cleanvar($_REQUEST['id']);

include (APPLICATION_INCPATH . 'htmlheader.inc.php');

	   // Page code goes here

include (APPLICATION_INCPATH . 'htmlfooter.inc.php');
?>

In line 2 we set a permission that is required to access this page, this permission is checked by auth.inc.php (line 8) and the user is prevented from accessing the page if their account does not grant the permission set here. This variable can be set to an array of permission numbers in order to require several permissions at once. The permissions are all stored in the 'permissions' database table.

In line 4 we include core.php, this provides database connectivity and configuration information and is required by auth.inc.php, functions.inc.php and the majority of SiT code.

Line 5 includes the largest file by far functions.inc.php, which contains the vast majority of functions that are used within SiT, you should know that we are in the process[1] of splitting this file up.

On line 8 we include auth.inc.php, this file checks that the user is logged in and that he/she has the appropriate permission(s) to view the page, the user is redirected elsewhere if not.

At line 10 we set a title for the page, note that we're setting it to a variable beginning $str... these are internationalisation variables and you can find a full list in i18n/en-GB.php (The master language strings file). header.inc.php will display this page title when we include it later on.

At line 13 we set up variables to receive data that is either GETed or POSTed from the browser, we list the variables in once place like this to keep things tidy, and we use a function called cleanvar() to remove anything nasty from the variable before we use it.

The rest is pretty obvious, a page header and a page footer with your code in between.

Forms

All forms for editing data should have a [Reset] button and a [Save] button and where appropriate a link to return to the previous page without saving.

This section is unfinished, ask on IRC if you want help.


Other tips

Using KDIFF3 with subversion

alias sd="svn diff --diff-cmd kdiff3 -x ' -qall '"

tip from: [2]

Merge all files from 3.x branch into current directory

kdiff3 --merge ../branches/3.x/. . -o .

SVN undo

To undo commit r123 just run

svn merge --change -123

svnmerge

- Some tips here http://www.dellroad.org/svnmerge/index

To check what changsets are available for merging run

svnmerge avail

Where there are multiple sources, you can specify which source like this

svnmerge avail -S trunk

To look at the diff of a changeset before applying it run

svnmerge avail -d -S trunk -r1234

Where //1234// is the revision number of the changeset

Once you're happy the changeset is ok to merge, run this to perform the merge

svnmerge merge -S trunk -r1234

Then to commit the merged changes run

svn ci -F svnmerge-commit-message.txt && rm svnmerge-commit-message.txt


resolve.sh

#!/bin/bash
kdiff3 --merge $1.merge-left.r* $1.merge-right.* $1.working -o $1 && svn resolved $1

Rollback an svn commit

svn merge -c -303 https://sitracker.svn.sourceforge.net/svnroot/sitracker/trunk/myfile.txt

See Also

Personal tools
project