Table of Contents

• Introduction
• Setup
• CVS
• Coding Style
• Communication
• Patches
• Release Management
• Database Development
• Editor Tips
• PHP Tips
• Rules for Development

Mantis, an open source project, allows you to contribute changes you make back to the core package. This allows others to benefit from your work and can help you from having to reimplement your changes after an upgrade. This page should provide useful information on procedures to ensure development goes smoothly.

Install and Set Up Apache + PHP + MySQL

• Apache
• PHP
• MySQL

Some sites that will guide you through a step-by-step installation and setup process.

• PHP/MySQL Tutorial - also covers installation and setup
• Another tutorial
• And another!

• Bad Blue - simple webserver with PHP support for Windows
• Apache+PHP - installation instructions
• PHPTriad - Apache, MySQL, PHP, PHPLIB, phpMyAdmin all in one! A bit outdated but still useful

Install phpMyAdmin

• phpMyAdmin

All you really need to do is edit the config.php file to be able to access your MySQL installation. Note that you will need to place phpMyAdmin in your web server directory so you can access it with your web browser. In order to secure this you should read the documentation and use a .htaccess file. If no one will be accessing your server it's not a big deal; just use common sense.

It may complain about magic_quotes_gpc. You can make sure this is on by looking in your php.ini file. Don't forget to restart apache for the settings to take effect. If that doesn't fix the warning just ignore it. I haven't had any problems.

Set Up CVS/SSH

• Gain our trust to gain developer access. Post patches to the mantisbt-dev mailing list. Visiting on IRC helps.
• After gaining developer access follow these instructions

You can store your SSH public key on the SourceForge server to avoid having to type your password each access.

If you are in unix, all you have to do is set the following environment variable: CVS_RSH=ssh

In bash: export CVS_RSH=ssh
In tcsh: set CVS_RSH ssh

To make this change permanent don't forget to put it in your .bash_profile, profile, .bashrc, .login, or wherever you put your environment variables. Don't forget to relogin!

If you're in Windows then read the SF documentation for Windows

Now check out the package:

cvs -z3 -d <username>@cvs.mantisbt.sourceforge.net:/cvsroot/mantisbt co mantisbt

You should now have the latest CVS snapshot. Move this directory to somewhere under your web root directory.

Change into the directory and type: "cvs -n update". The -n means no changes. It should successfully complete with (probably) no changes. As long as you are in this directory you won't need to type the long access string.

NOTE: You will have to disable the CVS_RSH=ssh if you want to use that login account for non-SF ssh'ed cvs projects.

Read the INSTALL directions and configure your config_inc.php file. Install the bugtracker into any database that you would like. If you do a lot of development you will likely be building multiple installations for testing. For example, I have one database called "bugtracker" as my primary database but also make a new one to test each release (mantis-0-15-1, mantis-0-15-2, etc.).

Open up your browser and test it out. The bugtracker directory (and any subdirectories) need to be web server (usually world) executable. Otherwise you will get errors about access denial or the images will fail to load. The files will be happy with a chmod of 644.

CVS reference - The key commands to learn are checkout (or co), update, commit (or ci), remove, and add.

Remember to set your EDITOR environment variable to your favorite command line editor. Otherwise you're likely to get dumped into vi, which is a horrible program to get stuck in for a first time user. To exit, hit ESC then : then q! then ENTER). The last line should look like:

:q!

Specify a message on the command line: eg. cvs ci -m "my message" file1 file2 file2.php* *.txt

cvs -n update

• Signup on the demo bugtracker
• Signup on the developer mailing list

• Files ending in just .php are files of some note

• config_inc.php has all the global sitewaide variable settings
• constants_inc.php has all CONSTANT values (they are UPPERCASE)
• core_* files contain all the functions used in the package - When you begin development you might want to make your own core_* file for your own test functions.

• The localization files are the .txt files
• The images are in the images/ directory (The directory structure will undergo changes shortly)

Help and Reference sites

• PHP Manual
• phpBuilder
• MySQL Documentation

Please follow the Mantis Coding Conventions document. Code not following the convetions will not be accepted!

Discussion and communication should occur in the mailing lists. Please try to keep discussions public. As an open source project much of the value and excitement comes from having an process that is open to the public.

Patches should be appliable using the unix "patch" command. Make sure your .patch or .diff files will be compatible or send explicit instructions on how to apply your changes. Always specify what release you are patching against. We prefer unified diffs. Please send all patches to the mantisbt-dev mailing list.

You'll want, of course, to use an editor you like. I myself do my development in Windows and use UltraEdit. You're free to use what you like and here are some features that you'll probably want.

• Column and row numbering.
• Goto Line Number
• Word wrap toggle.
• Multiple files.
• Searching across multiple files and recursively down directories.
• Search and replace across multiple files.
• Specify TAB spaces (I use 4).
• Syntax highlighting
• Trim trailing whitespace
• DOS 2 UNIX CR/LF conversions. Your editor must be able to save files with Unix-style line breaks. This means the \n character instead of the \r (Mac style) or \r\n (Windows style). You can confirm this by viewing the file in a hex editor.

This is a short crash course in PHP and things that you should take note of when using PHP.

1. PHP is very similar to C. Most contructs are similar so if you know C/C++/Java/Pascal you should quickly be up to speed.

   $a = 1;
   $b = 2;
   $c = $a + $b;
   echo $c;
   

   The preceding code creates variables $a, $b and $c and prints the number 3. Defining a variable is enough to create a variable in PHP.

2. PHP is also very loosely-typed and does type conversions on the fly.
3. You have to use the printf method of debugging (use the echo or PRINT command)

4. There is a keyword called global that is sometimes used inside functions. This is to allow functions to have access to global varaibles. By default global variables are locked out of local function scope. You have to explicitly tell the function what globals it can see.

5. It has 'OOP' but it is very primitive. It's good enough to be a useful addition but nowhere close to C++ or Java. Some of the nice class packages show you that it's good enough though.

6. PHP will let you know what line an error occurs on. Depending on your configuration PHP will hide warnings and notices from the user. In config_inc.php I have this line near the top of the file: error_reporting(E_ALL); This means 'report ALL errors warnings and notices as errors' (like -Wall in C/C++). Otherwise things like uninitialization errors will slip by you.

7. include()s are like C #includes, ie: makes everything look like one big text file

8. PHP has lots of string and date manipulation functions. If you think of a common action there is likely already a function that does it in PHP.

9. The string concatenation operator is the . symbol (period)

   "this plus"." this" is "this plus this"

   Since PHP is loosely-typed it would try to convert to numbers if you used the + operator.

10. PHP has garbage collection. You don't need to free resources unless you are using a lot in a single script (page). So unless you've decided to select all 50,000,000 records from your Big Brother database you probably don't have to worry about freeing database handles or closing files, etc. All open resources are automatically closed when the script finished execution (when the page loads in the browser). In general, don't worry about resources/performance until you get something to work first. After doing so you will probably have some insights into a better way to implement the feature(s).

11. Functions can be defined anywhere in PHP code. They must be defined before they are used (so be watchful of your include() ordering).

Coding Style

Please follow the Mantis Coding Conventions.

CVS commits

Please keep commits short and focused. Ideally you would check in all the files affects by your change(s) at one time. You should try to commit after every bugfix or feature addition. Make sure your commit note tells enough so that another developer (familiar with the project) can make sense of what changes were made. Information might include files, functions and variables that were modified.

e.g. cvs ci -m "Modified view_all_bug page so that column alignment is better across browsers" view_all_bug_page.php

Occasionally you can make do with a trivial message like "updates for release" or "tweaked formatting." This might be when you update the Changelog, or reformatted and cleaned up code, etc.

Communication

Please use the mantisbt-dev mailing list. This way there is a public record of development. If you have a matter you would like to discuss in private them emailing directly is fine.

Testing

In general I would prefer that you test using at least two browsers. This way most browser dependencies can be caught. I recommend testing with Internet Explorer for Windows and one of Firefox, Mozilla or Netscape. This captures the vast majority of actual users. Others that might be considered are Opera, Konqueror, Safari and OmniWeb.

Other rules

Make sure you sign up on the bugtracker and received developer access.

You can mark a bug as resolved if it is commited in CVS. Please don't close bugs until that release is publicly available.