Skip to content

Developer_guidelines

Ammar Abdulhamid edited this page Dec 28, 2020 · 24 revisions
Clone this wiki locally

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.
  • In the libraries directory, each file should contain single class and should be named according to it.

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 5.0.x releases are made from QA_5_0 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 run phpcs to validate your code using composer run phpcs 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

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 in 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