Developer_guidelines

Isaac Bennetch edited this page Jun 10, 2018 · 20 revisions

phpMyAdmin is Open Source, so you're invited to contribute to it. Many great features have been written by other people and you too can help to make phpMyAdmin a useful tool.

What to contribute?

You want to start contributing to phpMyAdmin and have no idea where to start? See Issue fixing section below.

If you speak a language besides English, take a look at the translations page for to see if your languages needs improvement.

Issue fixing

The best place to start is looking at the issue tracker and fixing a bug there. We have special issues tagged newbie which might be good starting point for you. There are separate repositories for the sql-parser and error-reporting server (which uses CakePHP) where you may also find tasks.

If you are about to implement new feature (not tagged newbie) it is good idea to ask on the development list whether the feature is worth implementing before working on it.

Structure

  • All files include libraries/common.inc.php (common functions) at the very top.
  • Only configuration data should go in libraries/config.default.php. Please keep it free from other code.
  • Commonly used functions should be added to libraries/core.lib.php or libraries/common.lib.php and more specific ones may be added within a library stored into the libraries/ sub-directory.

File names

  • The file names should match purpose of the code
  • In top level directory, there are scripts for user interface, starting with prefix indicating scope of actions (eg. db_* for database, table_* for table and server_* for server wide operations).
  • In the libraries directory, each file should contain single class and should be named according to it (there is still some legacy code which does not follow this).

Git setup

If you face any trouble with git, first check our Git wiki page, which contains more information and hints useful for our git workflow. There is also a private git repository for dealing with non-disclosed security issues, see Git_Security.

Branches in Git

  • master — All new features are developed in the master branch.
  • STABLE — This contains the current stable release; usually the most up-to-date version of phpMyAdmin that's commonly available. This is merged during the release process from the QA branch and is intended for users to automatically pull the most recent release. There is no reason to commit a fix specifically to this branch.
  • QA — Bug fix releases are created from the QA branches (e.g. all 4.1.x releases are made from QA_4_1 branch). QA is regularly merged in to master.
  • MAINT — Security or minor bug releases, when needed, are created in a MAINT branch, (e.g. MAINT_4_1_1 for 4.1.1 release). These are generally created only as needed from the RELEASE tags.
  • See Git for tips for using Git

Coding style

  • Please stick with PEAR coding style and please try to keep your code as simple as possible: beginners are using phpMyAdmin as an example application.
  • To verify coding style you can install PHP_CodeSniffer and validate your code using phpcs --standard=PMAStandard file.php, see phpMyAdmin coding standard for more details.
  • As far as possible, we want the scripts to be HTML 5 and CSS 2 compliant on one hand, they fit the PEAR coding standards on the other hand. Please pay attention to this.
  • The exception from PEAR coding standards is not wrapping long translated strings - it cause further complication to translators (embedded new lines in strings).
  • Variables used for phpMyAdmin Configuration Storage should use underscores; i.e. table_info not bookmarktable.

Indentation

  • Use an indent of 4 spaces, with no tabs.
  • See PEAR identation rules for more details.
  • If you're using vim as an editor, tabs will automatically be converted into 4 spaces by the directive on top of each file in the phpMyAdmin codebase :

/* vim: set expandtab sw=4 ts=4 sts=4: */

Make sure to add this to your .vimrc to make it work :

set modeline

Unit testing

We use several test suites to help ensure quality code. All new code should be covered by test cases to ensure proper Unit Testing.

Best practices

  • Please enable error reporting in PHP by error_reporting = E_ALL in php.ini.
  • Please enable showing PHP errors and warnings by the $cfg['Error_Handler']['display'] configuration directive, see Config#Error_Handler.
  • Please use gettext wrappers around all messages (__('Some text') or _ngettext() function). See Gettext for developers for more information.
  • The DBG extension (PHP Debugger DBG) is now supported by phpMyAdmin for developers to better debug and profile their code. Please see the configuration options for more information.
  • If you want to be really helpful, write an entry for the ChangeLog.

Join mailing list

  • Join the phpmyadmin-git mailing list if you are interested in every single commit (high volume).

Document the code

  • Use inline documenation.
  • PHP-Doc compatible for PHP.
  • JS-Doc compatible for JavaScript.
  • End user documentation, see Documentation

Author names

Except from "borrowed" libraries like PHPExcel and tcpdf, we do not put author names in source code. Here are the reasons:

  • over time, code gets modified so marking that some block of code was authored by X becomes misleading
  • the source-code revision control (git for us) already tracks authorship (line by line)
  • the author does not "own" the code; he may be more familiar with it but team members can modify it (and the community can propose patches)
  • significant authors are credited our documentation.

phpMyAdmin project and Software Freedom Conservancy

phpMyAdmin is member project of Software Freedom Conservancy, here are some documents which apply when asking for reimbursements:

API documentation

All used functions and files should be described in the phpDocumentor format.

Developer documentation can be viewed at https://develdocs.phpmyadmin.net/

What is planned?

Planning for past versions or general idea proposals:

Category:Devel

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.