====== Submitting Code ======
ADOdb is a community project, and its continued existence is reliant on both feature added by the maintainers and user submissions. To minimize wasted coding time and elongated discussion threads, here are a few guidelines
==== What is ADOdb? ====
Many people simply use ADOdb for single platform coding, to minimize the learning time involved in using PHP level database drivers. But ADOdb is also a cross database extraction layer, which allows the same code to be used across multiple platforms. So if you submit feature, it should be usable across multiple databases. Firstly, here's how we rank the drivers:
^ Importance ^ Drivers |
| Tier 1 | Native MySQL [mysqli], Native PostgreSQL [pgsql], Native SQL Server [mssqlnative], Native Oracle [oci8] ^
| Tier 2 | PDO (alltypes)[pdo_],ODBC(all types) [odbc],SQLite [sqlite3], Non-native SQL Server(mssql), IBM DB2(db2), Firebird(fbsql) |
| Tier 3 | Everything else |
This means that if you propose a new feature, i.e. one that will require it's own page in the documentation, it should be available on most, if not all of the **Tier 1** drivers at release to production. We understand that you may not be able to code that yourself, so you've got to be prepared to get help and agreement (probably from one of the maintainers).
==== Basic Rules ====
^ Scenario ^ Expected Actions ^
| You want to make a change that has no effect on the default functionality | - create an issue,explain the problem or feature.\\ - If the change affects **existing** installations, explain how you would support that |
| You want to change a feature | - If the feature change creates a scenario where the documentation would say "//for all drivers except xxxx, do this. Otherwise do this//", expect the request to be declined.\\ - If you cannot provide feature for Tier 1 drivers, open an issue and ask for help |
| You want to add new feature | Open an issue and explain the feature. You will be expected to provide some end user documentation that the maintainers can use as the basis for the docuwiki. Maintainers may decline to accept submissions where the only way of understanding the feature is dissecting the code. You should be able to provide at least one Tier 1 driver. The more drivers you can provide code for the more likely the maintainers are to accept the submission |
==== Scenarios ====
=== You found a bug ===
If you find a bug in a single driver, open an issue explaining the problem, if possible showing both what is happening and what should happen. If the maintainers agree it's a problem, and you have a fix for it, create a github pull request, referencing an issue.
=== You believe the current behavior in a driver is incorrect ===
These are often the most contentious discussions because we're likely to ask you to show how the behavior is wrong **in general**, and not just in your particular use case. In addition, if there is a problem, we need to be able to ensure that users who have relied on the apparently faulty behavior (possibly for years) aren't going to have problems if they upgrade to a version of ADOdb that has corrected behavior. That might mean, in the short term, an optional, parameterized change. Remember, ADOdb isn't an obscure little side project, there are normally 100-200 downloads per week, continually over a period of nearly 20 years.
=== You want to enhance the functionality of a specific function ===
Say, for example, you wanted to add the ability of the **mysqli** connector to use SSL connections to connect to the database.
- Start first by seeing how you can use the existing methods to provide access into your new codes. Don't, for example, modify the format of the **connect** function to require new, or modified parameters.
- You might, for example, use the **setConnectionParameter** method to inject the SSL parameters into the connection.
- If you need to add new class variables or methods, make sure the connection doesn't fail if they are not set.
- Make sure that your feature doesn't interfere with existing configurations.
=== Adding A New Feature ===
You might decide to offer a new method //**year**//, that provides a database independent method of obtaining a 4 digit year from a date field. If you use MySQL, then you might recognize the correct syntax as
SELECT DATE_FORMAT(field,'%Y');
You would then add the code into the drivers/adodb-mysql.inc.php file in a function like this
/**
* Formats the date into year only format YYYY
*
* @param str $field The name of the date to format
*
* @return str The SQL text
*/
public function year($fld)
{
$x = "DATE_FORMAT($fld,'%Y')";
return $x;
}
In order to fulfill the requirement for cross database compatibility, you should research the method of obtaining the same information from at least other Tier 1 databases. You would find that you would need to add code like this
SELECT YEAR(field) //mssqlnative, mssql drivers
SELECT TO_CHAR(field,'YYYY') // oci8 drivers, postgres drivers
Even if you cannot test these yourself because you have no access to the database, you can code them into your branch and put out a call on the issues page for help testing.
You need also to create some end user documentation, that can be used as a basis for docuwiki pages.
{{tag>[standards coding]}}