|
| 1 | +DEVELOPER INFO |
| 2 | +-------------- |
| 3 | + |
| 4 | +phpPgAdmin is Free/Open Source software and contributions are welcome from |
| 5 | +everyone. Please be sure to join the developers' mailing list: |
| 6 | + |
| 7 | + https://lists.sourceforge.net/lists/listinfo/phppgadmin-devel |
| 8 | + |
| 9 | +SOURCE REPOSITORY |
| 10 | +----------------- |
| 11 | + |
| 12 | +phpPgAdmin uses git for source control management. The phpPgAdmin git repository |
| 13 | +is hosted at github: |
| 14 | + |
| 15 | + https://github.com/phppgadmin/phppgadmin |
| 16 | + |
| 17 | +To clone the phpPgAdmin source to your development system, execute the following |
| 18 | +command: |
| 19 | + |
| 20 | + git clone git://github.com/phppgadmin/phppgadmin.git |
| 21 | + |
| 22 | +After making changes, generate a patch using "git format-patch" and submit it |
| 23 | +to the phpPgAdmin devel mailing list. |
| 24 | + |
| 25 | +Alternatively you can clone the phppgadmin repository on github and make a pull |
| 26 | +request. For details on how to make pull requests, see: |
| 27 | + |
| 28 | + https://help.github.com/articles/using-pull-requests |
| 29 | + |
| 30 | +Please note that submitting code is considered a transfer of copyright to the |
| 31 | +phpPgAdmin project. phpPgAdmin is made available under the GPL v2 license. |
| 32 | + |
| 33 | +Push access to the main phpPgAdmin git repository can be granted to developers |
| 34 | +with a track record of useful contributions to phpPgAdmin at the discretion |
| 35 | +of the phpPgAdmin development team. |
| 36 | + |
| 37 | +TIPS FOR DEVELOPERS |
| 38 | +------------------- |
| 39 | + |
| 40 | +When you submit code to phpPgAdmin, we do expect it to adhere to the existing |
| 41 | +coding standards in the source. So, instead of using your personal favourite |
| 42 | +code layout style, please format it to look like surrounding code. |
| 43 | +In general, we want the code to be portable, standard compliant (e.g. to W3C |
| 44 | +(X)HTML and CSS) and independent of specific configurations of PHP, the web |
| 45 | +server, PostgreSQL or the user browser. We also try to support as many versions |
| 46 | +as possible of these applications. |
| 47 | + |
| 48 | +Test your code properly! For example, if you are developing a feature to create |
| 49 | +domains, try naming your domain all of the following: |
| 50 | + |
| 51 | + * " |
| 52 | + * ' |
| 53 | + * \ |
| 54 | + * words with spaces |
| 55 | + * <br><br><br> |
| 56 | + |
| 57 | +Don't forget to make sure your changes still pass the existing Selenium test |
| 58 | +suite. Additionally, you should add or update the test suite as needed to |
| 59 | +cover your new features. |
| 60 | + |
| 61 | +If you are adding a new class function, be sure to use the "clean", |
| 62 | +"fieldClean", "arrayClean" and "fieldArrayClean" functions to properly escape |
| 63 | +odd characters in user input. Examine existing functions that do similar |
| 64 | +things to yours to get yours right. |
| 65 | + |
| 66 | +When writing data to the display, you should always urlencode() variables in |
| 67 | +HREFs and htmlspecialchars() variables in forms. Rather than use action="" |
| 68 | +attributes in HTML form elements use action="thisformname.php". This |
| 69 | +ensures that browsers remove query strings when expanding the given |
| 70 | +relative URL into a full URL. |
| 71 | + |
| 72 | +When working on database classes, always schema qualifing your SQL where it is |
| 73 | +possible with the current schema ($data->_schema) for pg73+ classes. Then don't |
| 74 | +forget to write your method for older classes which doesn't suppport schemas. |
| 75 | + |
| 76 | +When working with git, always make sure to do a 'git pull' both before you |
| 77 | +start; so you have the latest code to work with; and also again before you |
| 78 | +create your patch; to minimize the chance of having conflicts. If you plan to |
| 79 | +submit your code via github pull requests, we strongly recommend doing your |
| 80 | +work in a feature specific branch. If you want to submit multiple patches, |
| 81 | +they should all live in thier own branch. Remeber, smaller changes are easier |
| 82 | +to review, approve, and merge. |
| 83 | + |
| 84 | + |
| 85 | +COMMON VARIABLES |
| 86 | +---------------- |
| 87 | + |
| 88 | +$data - A data connection to the current or default database. |
| 89 | +$misc - Contains miscellaneous functions. eg. printing headers & footers, etc. |
| 90 | +$lang - Global array containing translated strings. The strings in this array |
| 91 | + have already been converted to HTML, so you should not |
| 92 | + htmlspecialchars() them. |
| 93 | +$conf - Global array of configuration options. |
| 94 | + |
| 95 | +WORKING WITH RECORDSETS |
| 96 | +----------------------- |
| 97 | + |
| 98 | +phpPgAdmin uses the ADODB database library for all its database access. We have |
| 99 | +also written our own wrapper around the ADODB library to make it more object |
| 100 | +oriented (ADODB_base.pclass). |
| 101 | + |
| 102 | +This is the general form for looping over a recordset: |
| 103 | + |
| 104 | +$rs = $class->getResults(); |
| 105 | +if (is_object($rs) && $rs->recordCount() > 0) { |
| 106 | + while (!$rs->EOF) { |
| 107 | + echo $rs->fields['field']; |
| 108 | + $rs->moveNext(); |
| 109 | + } |
| 110 | +} |
| 111 | +else echo "No results."; |
| 112 | + |
| 113 | +UPDATING LANGUAGE FILES FOR THE MONO-LINGUAL |
| 114 | +-------------------------------------------- |
| 115 | + |
| 116 | +If you need to add or modify language strings for a new feature, the preferred |
| 117 | +method is: |
| 118 | + |
| 119 | +* cd into lang/ subdirectory |
| 120 | +* modify english.php file only! |
| 121 | + |
| 122 | +If you've done it correctly, when you create your patch, it should only have |
| 123 | +diffs of the lang/english.php file. For more information on how the language |
| 124 | +system works, please see the TRANSLATORS file. |
| 125 | + |
| 126 | + |
| 127 | +UNDERSTANDING THE WORK/BRANCH/TAG/RELEASE PROCESS |
| 128 | +------------------------------------------------- |
| 129 | + |
| 130 | +All new work for phpPgAdmin is done against the git master branch. When we feel |
| 131 | +we are ready to do a new release, we create a branch (ex. REL_4-1). This |
| 132 | +becomes the stable branch for all future 4.1.x releases, and any bugfixes needed |
| 133 | +for 4.1 would go in that branch. |
| 134 | + |
| 135 | +When we release a new revision, we tag that at release time (REL_4-1-1), so a |
| 136 | +checkout of any tag should give you the same files that downloading the release |
| 137 | +would have given you. As a general rule, we do not introduce new features into |
| 138 | +existing stable branches, only bugfixes and language updates. This means if you |
| 139 | +want to work on new features, you should be working against the git master. |
| 140 | +Eventually we will call for another release, and that will be branched (REL_4-2) |
| 141 | +and the cycle will start over. |
| 142 | + |
| 143 | +On occasion we have created out-of-band branches, typically labeled as DEV_foo. |
| 144 | +These were used for temporary, concurrent development of large features, and |
| 145 | +should not be used by other developers. When development of those features is |
| 146 | +completed, the branches get merged in as appropriate, so no further development |
| 147 | +should occur on those branches. |
| 148 | + |
| 149 | +GETTING HELP |
| 150 | +------------ |
| 151 | + |
| 152 | +We prefer most discussion of development to take place on the phpPgAdmin |
| 153 | +devel mailing list, so that discussions can be archived and be searchable. |
| 154 | +However, if you are into IRC, a couple of us hang out on #phppgadmin on |
| 155 | +freenode, and occasionally discuss things there. |
0 commit comments