DevelopmentHowTo
 |
SiT! Manual | Developers Guide → DevelopmentHowTo | Chapter 6 |
Contents |
Essential Reading
- Mailing lists: sitracker-devel for SVN notifications and sitracker-devel-discuss to be able to join in with discussions about SiT development.
- Coding conventions
- Code documentation (See also the code docs for v3.x)
Getting Started with SiT Development
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.
- See this page on sourceforge for full instructions but very simply, you should checkout like this
svn co https://sitracker.svn.sourceforge.net/svnroot/sitracker/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.
- See also, Running unreleased versions.
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
 This is a draft article (or section) and is a work-in-progress. |
 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
