The file CHANGELOG.txt contains the Changelog for the recent Major version of VirtueMart. For every change you make to the source code you must make an entry to that Changelog.
Please use the date, your CVS username and the following characters to indicate a modification:
# -> Bug Fix
+ -> Addition
! -> Change
- -> Removed
! -> Note
An example entry could like like this:
06-09-2005 soeren
^ changed this and that
# fixed bug no. 75 [Bug desription]
+ added feature from request no. 56 [feature description]
Please keep your descriptions as readable as possible. A lot of people are following the changes and are interested in understanding all changes and their consequences.
If you had to make a change to the database schema, please indicate those changes with extra emphasis. Because you're not the only one working on a development version, please add all queries which are necessary to update a database to comply with your changes.
^ ## Database structure changed ##
ALTER TABLE mos_pshop_order_user_info ADD `extra_field_1` varchar(255) default NULL;
Please read the section „Database“ for all notes about the database and its scheme.
As there is no „real“ database abstraction in Mambo, we keep compatibility to MySQL.
All SQL queries must be compatible with at least MySQL version 3.23.
Future versions of VirtueMart will support Mambo versions from 4.5.1a until 4.5.2.3.
It's allowed to copy functionality from a later Mambo version
into VirtueMart's ps_main file to maintain downward
compatibility. The differences between Mambo
4.5 1.0.x and Mambo
4.5.x are too big as we could always keep downward
compatibility to Mambo 4.5. 1.0.x. On the other hand, it is necessary to stay up-to-date with Joomla!. Mambo and Joomla will be developed in two different directions. This process will someday lead to the effect that components written for Joomla, won't work on a Mambo 4.5.3 (or higher). VirtueMart will keep track with the Joomla development.
Javascript can be used in the frontend (is NO problem at all in the backend and for all administration pages).
But in the frontend all functionality that is used by a customer must also work with Javascript disabled! This includes Javascript-based category trees (always also include a section for people with disabled Javascript).
-
Use single quotes to refer to an index between brackets of an array (ex: $foo['name'] and not $foo[name] or $foo["name"])
-
Use single quotes instead of double quotes as much as possible because it's faster to parse.
-
$Id Tag inside the heading comment
Example: /* $Id: */
-
CVS will automatically fill this header tag with valid informaiton
-
Always run Mambo/Joomla! and PHP will full Error Reporting Level (E_ALL). You can change this level in Mambo's configuration (see „Server“ => Error Reporting Level) and in your PHP.ini.
-
Always initialize variables. (just $a=0 is initialization)
-
Use isset( $var ) to check if a variable has been set. Use empty( $var ) to check if Array indexes have been set or are empty.
-
Always use to delimit PHP code, not the shorthand. This is required for PEAR compliance and is also the most portable way to include PHP code on differing operating systems and setups.
All source code files in the repository shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Below are examples of such docblocks.
/**
* Short description for file
*
* Long description for file (if any)...
*
*
* @package VirtueMart
* @subpackage classes_product
* @author Original Author
* @author Another Author
* @copyright 2004-2005 VirtueMart Developer Team
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
* @version CVS: $Id:$
*/
/*
* Place includes, constant defines and $_GLOBAL settings here.
* Make sure they have appropriate docblocks to avoid phpDocumentor
* construing they are documented by the page-level docblock.
*/
/**
* Short description for class
*
* Long description for class (if any)...
*
* @author Original Author
* @author Another Author
* @copyright 2004-2005 VirtueMart Developer Team
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
* @version Release:
*/
class foo {
/** @var database Internal database class pointer */
var $_db=null;
/** @var object An object of configuration variables */
var $_config=null;
/** @var object An object of path variables */
var $_path=null;
/** @var mosSession The current session */
var $_session=null;
/** @var string The current template */
var $_template=null;
/** @var array An array to hold global user state within a session */
/**
* This function does something special.
* @param string The name of the product
* @param int The ID of the product
* @return string HTML Table with a "snapshot" of the product
*/
function myFunction( $arg1, &$arg2 ) {
}
}
?>
Short Descriptions
Short descriptions must be provided for all docblocks. They should be a quick sentence, not the name of the item, but the description of the „what does this file / class?“.
@license
VirtueMart is released under the GNU/GPL license. You should keep this license for best compatibility.
* @license http://www.gnu.org/copyleft/gpl.html GNU/GPL
@author
There's no hard rule to determine when a new code contributor should be added to the list of authors for a given source file. In general, their changes should fall into the "substantial" category (meaning somewhere around 10% to 20% of code changes). Exceptions could be made for rewriting functions or contributing new logic.
Simple code reorganization or bug fixes would not justify the addition of a new individual to the list of authors.
@copyright
Feel free to apply whatever copyrights you desire. When formatting this tag, the year should be in four digit format and if a span of years is involved, use a hyphen between the earliest and latest year. The copyright holder can be you, a list of people, a company, the PHP Group, etc. Examples:
* @copyright 2003 John Doe and Jennifer Buck
* @copyright 2001-2004 John Doe
* @copyright 2005 XYZ Corporation
This project has its SVN repository on the sourceforge.net SVN Server. You can checkout the module VirtueMart from svn.sourceforge.net. In order to obtain the source anonymously (read only) you need to know the following:
| Connection Type: https |
| SVN Server: svn.sourceforge.net |
| SVNROOT: /svnroot/virtuemart |
| Module Name: virtuemart |
| User: anonymous (no password required) |
Warning
The SVN server is case-sensitive. Fill in the details in your SVN Program (recommended: SmartSVN ) just as they are provided here.
The VirtueMart Project manages its documentation in the DocBook format. You can checkout the sources in the DocBook format and transform the DocBook source using an XSL Transformer into PDF, HTML, CHM or whatever else... All you have to do is checkout the module documentation from cvs.sourceforge.net.
| Connection Type: https |
| SVN Server: svn.sourceforge.net |
| SVNROOT: /svnroot/virtuemart |
| Module Name: documentation |
| User: anonymous (no password required) |
Warning
The SVN server is case-sensitive. Fill in the details in your SVN Program (recommended: SmartSVN ) just as they are provided here.
This section describes things that are generally applicable when using SVN; guidelines that are more specific to particular tasks or uses are described in the other sections.
Check in early, check in often. When you have made a change that works, check it in. Check in separate changes in separate commits (as much as possible). Don't be shy to check in work-in-progress, so long as it is minimally functional, or at least compilable without errors.
Use meaningful commit messages. Explain what bug the commit fixes, or what features it adds. Don't be too concise: "fixed typo" is too short; "fixed typo in error message" or "fixed typo in function name" is OK. The aim is to make it easier to find the desired change easily from just the commit messages (e.g. presented by svnweb).
The converse of this is including too much information. SVN automatically maintains information like the date and time of the commit, who made the commit, what code was changed, etc. You don't need to include it in the commit message yourself.
If in doubt, lay down a tag. Tags are useful for pinning down a particular version of the code, e.g. one that is being run in service, or just before a big change or import. They are also used to identify branches. Tag names should be short and meaningful, like variable names. For example, virtuemart-20060923, pre-new-resolver, fanf-patches, corresponding to the uses mentioned above. Tags should be commented in the modules file.
Comment the modules file. It defines the modules in the repository, which in the simplest case are just aliases for a directories in the repository. SVN can also combine several directories that together form a module. For each module in the file there should be a comment describing the contents of the module, when it was created and who by, and a description of the tags and branches used by the module. (Tags don't get commit messages of their own, hence the latter requirement.)
Most of the guidelines in this section are common sense, but it's worth while re-iterating them in the context of SVN because it has implications that might not be immediately obvious.
Never, ever reformat code. This is a really bad thing to do because it makes diffs hard to understand and apply. Upstream authors won't accept patches against reformatted code. Bugfixes and patches against the upstream code won't apply. New versions of the upstream code can't be imported. Real changes get hidden in the mass of reformatting.
No-one's favourite coding style is significantly better or worse than anyone else's so reformatting code provides no advantage to oppose the disadvantages.
Use the same coding style as the code you are editing. This is a corollary to the previous subsection. It is easier for people reading the code if it uses consistent layout rules throughout, so when you are editing someone else's code the code you add should be in the same style.
Tabs are four characters wide. This is also a corollary to the previous subsections. Although indentation sizes vary greatly, tabs are almost universally four characters, so using a different setting is liable to cause confusion or even reformatting.
Commit messages are not a substitute for comments, or vice versa. Comments should describe data structures and why the code does what it does; commit messages should explain why code was changed.
Include SVN $Header$ strings in your code. This makes it easier for people to know which version of a file they have and where it came from, so that they can usefully refer to the file's SVN history to find out about bugs and fixes, etc.
If your repository is configured appropriately, use the custom tag instead of $Header$.
Changes to the main db schema require a that an upgrade patch is posted as well. Your change will be backed out if you don't provide a patch as well.
First of all you need to make an entry in the Changelog, including the SQL Queries to update a database scheme.
All changes to the database scheme are collected in an SQL file. There's a file for each minor version jump, e.g.
UPDATE-SCRIPT_com_virtuemart_1.0.0-to-1.1.0.sql
The file can be found in the subdirectory /sql.
A user must see which version of VirtueMart this SQL patch file applies to and to which version it updates the db scheme.
In this case the SQL file would update a db scheme from version
1.0.0 to 1.1.0