com web/php: changes to get-involved and introduce build-setup: build-setup.php get-involved.php
| From: | Joe Watkins | Date: | Tue, 17 Sep 2013 21:37:01 +0000 |
| Subject: | com web/php: changes to get-involved and introduce build-setup: build-setup.php get-involved.php | ||
| Groups: | php.webmaster | ||
| Request: | Send a blank email to php-webmaster+get-16623@lists.php.net to get a copy of this message | ||
Commit: 836725ee4d0c8589140922a8f05a0a9a2089ea4e
Author: krakjoe <joe.watkins@live.co.uk> Tue, 17 Sep 2013 22:37:01 +0100
Parents: 8ab08254bcd361f1e439ee1b130fc08c4b89b946
Branches: master
Link: http://git.php.net/?p=web/php.git;a=commitdiff;h=836725ee4d0c8589140922a8f05a0a9a2089ea4e
Log:
changes to get-involved and introduce build-setup
Changed paths:
A build-setup.php
M get-involved.php
diff --git a/build-setup.php b/build-setup.php new file mode 100644 index 0000000..790beb7 --- /dev/null +++ b/build-setup.php @@ -0,0 +1,167 @@ +<?php +// $Id$ +$_SERVER['BASE_PAGE'] = 'get-involved.php'; +include_once $_SERVER['DOCUMENT_ROOT'] . '/include/prepend.inc'; + +$SIDEBAR_DATA =' + <p> + This page is intended to help setup a development environment for PHP, if mistakes are found + please <a href="http://bugs.php.net">report</a> them. + </p> +'; + +site_header("Get Involved", array("current" => "community")); + +?> +<h2>Operating System Preparation</h2> +<p> + Improving PHP requires a working build environment to test changes, the following section deals with setting up a working build environment. +</p> +<p> + Your build environment should have an appropriate toolchain that includes a working C compiler, + for those not working in Microsoft Windows, you will need a working, compatible autotools installation, and at the very least a shared copy of zlib. +</p> +<p> + For most *nix like operating systems, some external dependencies may be required to bring a build to completion; + if a build fails because of missing headers or libraries, issuing a variant of the following command should resolve those dependencies, allowing the build to continue: + <ul> + <li>[sudo] yum|apt-get|ports install package[-dev[el]]</li> + </ul> +</p> +<p> + For those working in <i>Ubuntu Linux</i>, you can run the following command to automate the installation of dependencies: + <ul> + <li>sudo apt-get build-dep php5</li> + </ul> + If the compilation of <i>an extension</i> should fail because of missing dependencies, <i>Ubuntu Linux</i> can attempt to automate the resolution of those dependencies by issuing: + <ul> + <li>sudo apt-get build-dep php5-<i>extname</i></li> + </ul> +</p> +<p> + The following table shows what is required for Microsoft Windows users to build PHP: +<p/> +<table> +<tr> + <th>PHP</th> + <th>Visual C++</th> + <th>MS SDK</th> + <th>DEPS</th> + <th>PHP SDK</th> +</tr> +<tr> + <td align="center">5.3</td> + <td align="center">Visual Studio 2008</td> + <td align="center">6.1</td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/deps-5.3-vc9-x86.7z">x86</a></td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/php-sdk-binary-tools-20110512.zip">here</a></td> +</tr> +<tr> + <td align="center">5.4</td> + <td align="center">Visual Studio 2008</td> + <td align="center">6.1</td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/deps-5.4-vc9-x86.7z">x86</a></td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/php-sdk-binary-tools-20110915.zip">here</a></td> +</tr> +<tr> + <td align="center">5.5</td> + <td align="center">Visual Studio 2008</td> + <td align="center">6.1</td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/deps-5.5-vc9-x86.7z">x86</a></td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/php-sdk-binary-tools-20110915.zip">here</a></td> +</tr> +<tr> + <td align="center">5.5</td> + <td align="center">Visual Studio 2012</td> + <td align="center">N/A</td> + <td align="center"> + <a href="http://windows.php.net/downloads/php-sdk/deps-5.5-vc11-x86.7z">x86</a>, + <a href="http://windows.php.net/downloads/php-sdk/deps-5.5-vc11-x64.7z">x64</a> + </td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/php-sdk-binary-tools-20110915.zip">here</a></td> +</tr> +</table> +<p><b>Note:</b> If a Windows SDK is required, it is advised to install the SDK <i>before</i> Visual Studio.</p> + +<h2>Workspace Preparation</h2> +<p> + Windows users should now download and unzip the PHP SDK to their workspace and execute the following commands in an appropriate Visual Studio Console: +</p> +<p> + Visual Studio 2008: + <ul> + <li>setenv /xp /Release /x86</li> + </ul> + Visual Studio 2008 and 2012: + <ul> + <li>cd C:\path-to-workspace</li> + <li>bin\phpsdk_setvars.bat</li> + <li>bin\phpsdk_buildtree.bat phpdev</li> + </ul> + Windows should now change to the directory C:\path-to-workspace\phpdev\<i>VCXX</i>\<i>XARCH</i>, and consider it the root of the workspace for the current build. +</p> +<p> + The next step for everyone is to obtain the versioned PHP sources via git: + <ul> + <li>git clone -b BRANCH https://github.com/php/php-src .</li> + </ul> + BRANCH should be replaced with an appropriate branch name, for example <i>PHP-5.5</i>. +</p> +<p> + At this point you have a working build environment and the vanilla sources for your chosen branch of PHP, it is a good idea, before you change anything at all, to create a new branch and switch to it, in preparation for your awesome changes to come: + <ul> + <li>git checkout -b my-awesome-changes</li> + </ul> +</p> +<h2>Building Your Development PHP</h2> +<p> + All operating systems now converge on (near as makes no difference) the same solutions for the rest of the build process: + <ul> + <li>buildconf: generates the configure script for PHP</li> + <li>configure: configures the build of PHP and creates Makefile</li> + <li>make: builds PHP</li> + <li>make test: runs testsuite</li> + <li>make install: installs PHP</li> + </ul> +</p> +<p> + For Microsoft Windows operating systems, those commands looks like this: + <ul> + <li>buildconf</li> + <li>configure --with-prefix=C:\my-awesome-php</li> + <li>nmake</li> + <li>nmake test</li> + <li>nmake install</li> + </ul> +</p> +<p> + While for the rest of us, those commands look like this: + <ul> + <li>./buildconf</li> + <li>./configure --prefix=/opt/my-awesome-php</li> + <li>make</li> + <li>make test</li> + <li>make install</li> + </ul> +</p> +<p> + The <i>configure</i> script has the ability to customize almost every aspect of PHP, to ellicit help at the console pass <i>--help</i> + as the only argument to <i>configure</i></p> +<p> + When <i>configure</i> executes, it saves the options passed in to a re-usable <i>config.nice</i> which executes <i>configure</i> when invoked. +</p> +<p> + Upon successful completion of a build, it is recommended to run the test suite, this will help you to identify regression problems in your work, + running the test suite can take a while; go out for a run, or a burger. +</p> +<p> + It is also possible to run a set (directory) of tests in the following way: + <ul> + <li>[n]make test TESTS=sapi/cli</li> + </ul> +</p> +<?php +site_footer(array('sidebar'=>$SIDEBAR_DATA)); + +/* vim: set et ts=4 sw=4 ft=php: : */ + diff --git a/get-involved.php b/get-involved.php index 1de2e43..f89d0ac 100644 --- a/get-involved.php +++ b/get-involved.php @@ -16,543 +16,42 @@ $SIDEBAR_DATA =' site_header("Get Involved", array("current" => "community")); ?> -<h2>Improving PHP</h2> +<h2>Contributing to PHP</h2> <p> - This particular article assumes you are running <i>Ubuntu Linux</i>. + Anybody who programs in PHP can be a contributing member of the community that develops and deploys it; + the task of deploying PHP, documentation and associated websites is a never ending one. + With every release, or release candidate comes a wave of work, which takes a lot of organization and co-ordination. </p> <p> - To get a working build environment you need to run the following command; - <ul> - <li>sudo apt-get build-dep php5</li> - </ul> -For any extension that requires 3rd party libraries you need to install those libraries. -The simplest way to accomplish that is to to use <em>apt-get</em> to install the Ubuntu build dependencies for that particular extension. For example, if you want to build PHP with <a href="/manual/intl">intl</a> support you have to run; - <ul> - <li>sudo apt-get build-dep php5<em>-intl</em></li> - </ul> -to install the ext/intl dependencies. -</p> -<p> -To actually build PHP with ext/intl support you need to configure PHP to enable it, f.e. - <ul> - <li>./configure --enable-intl</li> - </ul> - The rule of thumb for configuring PHP is;<br /> - <ul> - <li>If its a pure PHP functionality use <em>--enable</em>extension-name<br /> - Example; - <ul> - <li>./configure --enable-soap</li> - </ul> - </li> - <li>And for extensions wrapping external libraries use <em>--with</em>-extension-name<br /> - Example; - <ul> - <li>./configure --with-pgsql</li> - </ul> - </li> - </ul> - But as you saw with ext/intl, rules are meant to be broken - so you <em>should</em> check <i>./configure --help</i> first.<br /> - When PHP encounters unknown configure argument you will be notified in the end, so you can modify your arguments and re-run ./configure before executing <em>make</em>. -</p> -<p> -PHP creates a script called <em>config.nice</em> after every successful <em>./configure --some --arguments</em> so you don't have to remember all the options you passed to ./configure every time you want to rebuild PHP, running <em>./config.nice</em> will do that for you -</p> - -<p> -Once you have the build dependencies installed you'll need to checkout PHP from Git, configure and build it; -<ul> - <li>git clone -b PHP-5.4 http://git.php.net/repository/php-src.git php-5.4</li> - <li>cd php-5.4</li> - <li>./buildconf</li> - <li>./configure (see the <a href="#config.nice">shell script helper below)</a></li> - <li>make all test</li> -</ul> -</p> - -<p>While `make all test` is running we recommend you go out for a run, -it can take a while. When you come back, submit -the test results, but then try to track down one of the failed tests and -figure out why it failed. The tests are very simple. In the failed test -summary at the end a failed test shows up as:<br /> -<em>CLI php -m [sapi/cli/tests/018.phpt]</em> -<br /> -That's a short description of the test and the filename of the test itself. -For a failed tests, we create some files in the test dir. Go to sapi/cli/tests -and you will find these files: -<ul> - <li>018.phpt - the full test file</li> - <li>018.php - the php code that was run for the test</li> - <li>018.out - the actual output from the test</li> - <li>018.exp - the output that we expected</li> - <li>018.diff - the diff between the actual and expected</li> -</ul> -Once you have fixed something, you can re-run the tests for just that set of -tests with: -<ul> - <li>make test TESTS=sapi/cli</li> -</ul> -</p> -<p> -To run more tests, run ./configure and enable as many extensions as possible. -</p> -<p id="config.nice"> -Here is the shell script I use on an Ubuntu box: -<pre> -#! /bin/sh -'./configure' \ -'--with-apxs2=/usr/bin/apxs2' \ -'--with-curlwrappers' \ -'--with-gd' \ -'--with-jpeg-dir=/usr' \ -'--with-png-dir=/usr' \ -'--with-vpx-dir=/usr' \ -'--with-freetype-dir=/usr' \ -'--with-t1lib=/usr' \ -'--enable-gd-native-ttf' \ -'--enable-exif' \ -'--with-config-file-path=/etc/php5/apache2' \ -'--with-config-file-scan-dir=/etc/php5/apache2/conf.d' \ -'--with-mysql=/usr' \ -'--with-zlib' \ -'--with-zlib-dir=/usr' \ -'--with-gettext' \ -'--with-kerberos' \ -'--with-imap-ssl' \ -'--with-mcrypt=/usr/local' \ -'--with-iconv' \ -'--with-ldap=/usr' \ -'--enable-sockets' \ -'--with-openssl' \ -'--with-pspell' \ -'--with-pdo-mysql=/usr' \ -'--with-pdo-sqlite' \ -'--enable-soap' \ -'--enable-xmlreader' \ -'--with-xsl' \ -'--enable-ftp' \ -'--enable-cgi' \ -'--with-curl=/usr' \ -'--with-tidy' \ -'--with-xmlrpc' \ -'--enable-mbstring' \ -'--enable-sysvsem' \ -'--enable-sysvshm' \ -'--enable-shmop' \ -'--with-readline' \ -'--with-mysqli=/usr/bin/mysql_config' \ -'--prefix=/usr/local' \ -"$@" -</pre> -<p> -There are also README.TESTING and README.TESTING2 text files in the root -directory if you want to learn more about the testing mechanism. -</p> - - -<hr /> - -<h2>Contributing</h2> -<p> - The PHP project is so much more than just the scripting language on which it is - focused. It is a vibrant community of developers scratching related itches, - hoping their work will benefit others. PHP.net hosts a set of projects - focused around the "flagship product," the PHP language, surrounding it - with sub-projects for documentation, website maintenance, adding extra - functionality with extensions, and so on. -</p> - - -<p> - The PHP community is without a doubt, in my opinion, one of the greatest - communities in the world. It has a lot to offer besides good friends and a fun - working environment. It is a community where things can happen very fast, with - many people involved, contributing back "upstream" to PHP in various - capacities, from user-contributed notes to the manual to new killer language - features. There is always room for new contributors though, and PHP.net really - needs your help so it can continue the success of past years. In this article - we will explore how the PHP.net project works and how you can contribute to it. + With the introduction of release managers comes a smooth release process, but still help is needed: + testing release candidates, finding and squishing bugs in tests, documentation, and sources. </p> - +<h3>Four Best Ways to Contribute</h3> <p> - There are a lot of ways in which you can contribute to and influence the project; - participating on mailing lists, filing bug reports, and adding helpful notes - to the manual are all examples of valuable contributions. You don't have to - develop a new JIT compiler, or even know the first thing of - developing a language for that matter, to be able to contribute back. Whatever - you fancy, I am sure you can find a challenging task on PHP.net to solve. Or - are you maybe just looking for some brain-dead task on which to spend time - - but still want to make a difference? We have several of those too! + <ol> + <li>Running test suites in <a href="http://qa.php.net/">RC</a> and <a href="http://php.net/releases">release</a> distributions of PHP</li> + <li>Help finding and diagnosing failed tests <a href="http://qa.php.net/write-test.php">phpt documentation</a></li> + <li>Filing and resolving bug reports at <a href="http://bugs.php.net">bugs.php.net</a></li> + <li>Help maintain and or translate documentation files at <a href="http://edit.php.net">edit.php.net</a></li> + </ol> </p> - - +<h3>Development of the PHP source</h3> <p> - Before we go deeper into ways you can contribute and how to do so, let's take - a step back and look at who actually leads the development and how things are - done within PHP.net. + Someone hoping to become involved in the maintanence and development of the source should be experienced in all of the areas mentioned above, + this creates a strong team; everyone knows how every other part of the project works. </p> - - <p> - One of things I love most about working with Open Source Software like PHP is - the freedom. If I have an itch, I scratch it! If I want to work on new - features or document all the kinks and quirks of PHP, I can. We have the - freedom to work on exactly the things we care about and want to do. - There is no one person in charge or policing of the project, it is a community - effort. All decisions are made in the open after the contributors - participating in the discussion reach "general consensus" on the topic or - if - all else fails - after a vote on the subject. As within any community, there; - are members that have earned karma and respect through contributions to the - project, and their meaning and views usually carry more weight than a total - stranger from whom no one has heard before. Karma, like trust, needs to be - earned. + You will also need experience in C programming as PHP is written entirely in C. </p> - - -<p> - To gain karma you basically need to prove to the community that you aren't - just a nut-job and show that you can be trusted to think not only about today, - but tomorrow as well. Being active on the developers' mailing lists, - digging into bug reports, posting patches and unit tests, and generally - trying to help out and contribute to the project are great ways to gain a - lot of karma points very quickly. -</p> - - -<p> - All of the PHP.net projects (from PEAR, to PECL, to websites and - documentation, to the PHP language itself) have - long-time members which could be considered the "leaders" of the respective - projects by the community, but that really doesn't mean anything other than - "if no one knows the answer, ask him." The "leader" isn't going to tell you to - do anything, other than maybe ask you to revert a bad commit, but anyone can - do that. It is totally up to you to decide whether or not to work on some - things. In the end, the final say on the matter is up to the contributor who - is actually doing the work. -</p> - - <p> - The PHP.net project has mailing lists for most aspects of the project where - all important decisions are made. For example discussions and decisions about - the language happen on the internals@lists.php.net mailing list - (internals-win@lists.php.net for Windows-specific things such as packaging, - porting features not available yet on Windows, et cetera). All discussions - are open to whomever wants to participate. All you need to do is to sign up - to the mailing list and follow the discussions - and chime in if you have - something to add. Please take a few moments to familiarize yourself with the - mailing list "rules" before you go all crazy on the lists. For the rules that - are generally followed on all PHP mailing lists, please see the - <a href="http://php.net/reST/README.MAILINGLIST_RULES">Mailinglist Rules</a>. -</p> - - -<p> - Although most of the PHP internals contributors make their living writing PHP - applications, feedback from other users is crucial to the development of the - language; your voice does matter. Keep in mind, however, that flaming - and/or talking down to the developers that spend most of their free time - working on the project may not exactly be the best approach to get your point - across. Take a look at the <a href="http://php.net/mailinglists">Mailing Lists</a> for the most - popular mailing lists and see if any of them interest you, then sign up! -</p> - - -<p> - Even though most of the mailing lists are very active, not everything that is - contributed to PHP needs to be approved there first. For example, minor - features are often simply committed directly to Git without asking or telling - anyone. These are typically things for which a developer working on an - external application saw a need and decided to add, in case anyone else might - need it in the future. PHP has a great peer review process so it's very hard - to "sneak" things in. Every commit to Git is reviewed by quite a lot of people - who are interested in what is going on - or who simply enjoy reading code. If - a reviewer discovers issues with the commit, he or she will send a quick reply - to the commit email and discuss it on the developers list. Often the peer review - results in extending the new feature and/or fixing unexpected behaviour, but - it can also result in removal of the feature as a whole if the community - doesn't see any need for it. -</p> - - -<p> - To help streamline part of the decision process and keep track of ideas, - proposals, and TODO lists, PHP has a wiki located at - <a href="http://wiki.php.net">wiki.php.net</a>. This has proven to be a valuable resource when - developing new features, creating RFCs, and getting approval for things - before wasting time on a rejected feature. Discussions on controversial - features pop up on the mailing lists regularly, but with the help of the - wiki people can easily browse through previous discussions and see the - reasons for rejection. The wiki contains a lot of great information and is - definitely worth browsing for all those interested in the overall PHP.net - project. It not only covers RFCs, but also has a lot of information about - how various other things work; missing documentation, suggestions, - "internal" parser engine information, infrastructure docs, and even some - TODO lists are all examples of things included in the wiki. -</p> - - - - -<h3>So, how to get involved?</h3> -<p> - There are a lot of ways you can contribute to the project, it simply depends on what you fancy. -</p> -<ul> - <li> - Do you want to work on UI design, or general website development? - Looking for a place to experiment with emerging web technologies? We have - several websites, both 'internal' and external, many of which could use a - facelift, while others, quite frankly, could benefit from a complete - rewrite. - </li> - <li> - Do you enjoy technical writing? Discovering the inner workings of things? - Being the first one to try out not-even-yet-released features? Join the - documentation team. Having a good understand of C will help when documenting - new features, but there will always be people around to explain features to - whomever wants to document them. - </li> - <li> - Want to show off your sysadmin skillz? PHP.net has dozens of servers - needing some love. Everything from simple web servers to complicated mail - setups, DNS and rsync servers to build-boxes and website mirroring - infrastructure. - </li> -</ul> - -<p> - Getting involved is a lot easier than most people think - and chances are that - you are already involved in one way or another. You don't need an Git account - and commit access to get started - Git accounts need to be earned. Registering - on the mailing lists related to the topic in which you are interested - and - actively participating in the discussions - is a good start toward getting - your request for an Git account granted. Browse the wiki to see if there are - outstanding TODO items you can help to clear, for example. Another great way - to get involved and really help out is by reviewing the bug tracker for bugs - you could potentially fix, or perhaps for which you could write a unit test. - Sending several pull requests, or attaching patches to bug reports will - quickly show that you are interested and serious about your desire to - contribute. Eventually someone will get annoyed with the amount of time - they must spend to commit your patches for you, and will probably respond - with something along the lines of, "Stop bothering me. Do it yourself!" and - ask you to submit the Git account form. Mission accomplished! -</p> - - - - -<h3>Tips</h3> -<ul> - <li> - <h4>Mailing Lists</h4> - <p> - To register with any PHP mailing list, just send a blank email to - <listname>-subscribe@lists.php.net. For example if you want to register - for the PHP internals developers discussion list, send an email to - internals-subscribe@lists.php.net. - Alternatively, filling out the form at <a href="http://php.net/mailinglists">php.net/mailinglists</a> will - register you for the list (or lists) you choose. That page also lists some of - the most popular mailing lists and describes the intention of the lists. - Again, remember to refer to the rules prior to joining the discussion, or you - may be scorned for a faux-pas such as top-posting your reply to a thread - oh the horror! - </p> - </li> - <li> - <h4>The Bug Tracker</h4> - <p> - Filing a bug report is an art. It isn't very complicated, but you do - have to think about what you are reporting. Quickly looking through - the existing reports to see if your issue has already been reported - will take you less than five minutes, and the chances are quite good that - you aren't the first one to identify the issue. However, if you are, - we greatly appreciate your time and effort in reporting it. If at all - possible, provide a short example of how the issue can be reproduced, - and mention what you expected to happen versus what actually happened. - Simple steps like these will drastically increase the chances of - someone picking up the report and attempting to fix the issue. While - there is no registration or login required to file a bug report, a - valid email address must be provided just in case the developers need - more information from you, as well as for you to receive status - updates on your report. A page explaining how to file a "report that - someone will want to help fix" is available on - <a href="http://bugs.php.net/how-to-report.php">bugs.php.net/how-to-report.php</a>. Please read through it - before filing a bug report for the first time. - </p> - </li> - <li> - <h4>Getting Started With Contributing</h4> - <p> - Unsure which task to tackle first? Stuck on a problem? Need a - quick brainstorming session? IRC is a very convenient way to get - help quickly for smaller things, such as "where was the Git module - for zyx?" or if you simply want to run an idea by people to get - their opinions - or even just to hang out. There aren't any - "official" IRC channels for the PHP project, but a good chunk of - contributors hang out on EFNet on the #php.pecl, #php.doc and #pear - channels. The mailing list archives also contain a lot of information - and are definitely worth searching for ideas and inspiration. If - you think your question can benefit others coming after you, - consider asking it on the mailing list so the next person doesn't - have to ask it again. - </p> - </li> - <li> - <h4>Less Is More</h4> - <p> - When you are ready to contribute to the project please don't try - to tackle the biggest issues and expect to fix them right away. - Start with smaller tasks and learn the ways of the project and - participate in discussions on the mailing lists. Larger issues - take more time and experience within the project, which is not - something on which newcomers should focus. Take your time and - solve the task as best as you possibly can. Read up on the Coding - Standards and try to be consistent in your work. We have lost too - many people who jump right on the larger tasks only to vanish few - days later, having given up on the task because it took more time - and effort than they initially anticipated. - </p> - </li> -</ul> - - - -<h3>So what kind of projects does PHP.net have?</h3> -<ul> - <li>PHP (the language)</li> - <li>PECL (various additional PHP functionality in the form of extensions)</li> - <li>PEAR (reusable PHP component library)</li> - <li>Websites (php.net, qa.php.net, doc.php.net, edit.php.net, etc.)</li> - <li>Documentation (PHP, PECL, PEAR, etc.)</li> - <li>System administration (mail servers, web servers, build-boxes, monitoring, etc.)</li> - <li>Etc., etc., (etc.)</li> -</ul> - -<p> - If you can't find something on which to work within PHP.net, you will have a - hard time finding it elsewhere. Introducing every project is beyond the scope - of this article, but we'll cover some of the projects that don't have entry - points that are too steep for newcomers. -</p> - - - -<h3>The Documentation Project</h3> -<p> - The main focus of the documentation project (phpdoc) is to document the PHP - language (and PECL extensions) with usage examples, FAQs, and tracking changes - in behaviour. The documentation is written in XML using the Docbook format - with English as the primary language. This is then translated into several - different languages by dedicated translation teams. The phpdoc team also - maintains sets of scripts to simplify the work: generation of skeletons for - new extensions and functions based on Reflection information, extracting INI - options, and various related utilities to extract information from the PHP - source code are all examples of tools used to make writing documentation - easier. The primary mailing list for phpdoc is phpdoc@lists.php.net, where - contributors coordinate their efforts and ask for feedback, suggestions, and - help. The list also covers the phpdoc sub-projects, such as the PhD and PhD - O.E. applications. Each translation team also has its own mailing list: - doc-<country-code>@lists.php.net. For example, doc-fr@lists.php.net for - the French translation list. -</p> - -<p> - A web application, called "PhD Online Editor" (PhD O.E), which aims to help - documentation editors focus on the content itself, rather than Docbook and XML - logistics, is under development at <a href="https://edit.php.net">edit.php.net</a>. It is getting - more and more popular, especially for newcomers who aren't comfortable with - Docbook. It has a very rich interface and desktop application feeling to it, - and abstracts most of the XML magic from the contributor. One of the goals - of PhD O.E. is to get more people involved with the documentation effort, - and therefore it will allow anonymous users to "login" and use the - application. Modification, validation, translation, creation of new files, - and everything else you need for writing documentation is possible without - an Git account. When saving changes, a patch will be created and saved to - the "patch queue," while pending approval by someone with Git karma to - commit the changes. PhD O.E. also bundles a variety of scripts to ensure the - docs use a consistent structure, allow the contributor to view undocumented - functions, and check the translation status of an entry (among other things). -</p> - -<p> - The team is also developing a Docbook rendering engine, called "PHP-based - Docbook Rendering" (PhD), to transform the Docbook XML into various different - formats, such as HTML, CHM, PDF, Unix manual pages, and the online format you - see while browsing the <a href="http://php.net/manual">PHP Manual</a>. The application was written with - performance in mind and can render the entire PHP manual in less then five - minutes, whereas the previous tool chain would take over an hour for the same - task. PhD has received a lot of attention from various people and projects - using Docbook, and is now also in use outside of PHP.net for the rendering of - Docbook manuals. -</p> - - -<p> - Last, but not least: the team also maintains a website on - <a href="http://doc.php.net">doc.php.net</a> which aggregates translation - statistics, tutorials, and the documentation HOWTO. -</p> - -<p> - The project offers much more than just documentation, and is probably the - project to which it is easiest to start contributing. If you enjoy working - with XML, PHP, JS, documentation, writing articles, or simply want to dig - into the PHP internals from a different angle, this is the place to be. -</p> - - -<h3>The Websites</h3> -<p> - No surprise there, the webmaster team maintains several websites, and is - responsible for maintaining the mirroring infrastructure and related tasks. - The websites contain a lot of information; everything from user group meet-ups - and conference listings, to tips & tricks and documentation, and - everything between. It is also the primary public source for release - information, as well as the general entry point for people looking into PHP. -</p> - -<p> - To get up and running is very simple: just follow the points on - <a href="http://wiki.php.net/web/mirror">wiki.php.net/web/mirror</a> - and you are all set. Once you have poked around a little you can look - into the other websites, like qa.php.net, master.php.net and pecl.php.net. -</p> - -<p> - Recently, work on redesigning the main website from the ground-up was started. - Unfortunately, this effort has stalled a bit over the past several months - due to a lack of contributors interested in being actively involved. - The idea is simple: design a completely new layout and refactor the current - content to make it more accessible. -</p> - -<p> - Joining the redesign effort is a great entry point for those interested in - markup, CSS, and general website development. Check out - <a href="http://wiki.php.net/web/redesign">wiki.php.net/web/redesign</a> - and contact php-webmaster@lists.php.net if you are interested in contributing. - You will be welcomed with roses! -</p> - - - -<h3>Conclusion</h3> -<p> - PHP.net has a lot of areas to which you can contribute: everything from - hardcore development to managing user-contributed notes in the manual; - from debugging issues in bug reports to writing articles about new features - for the manual. In this article we only covered the tip of the iceberg, - mentioning only a small sample of concrete projects that do a lot more than - initially meets the eye, and which welcome all the help they can get. - We have also touched on how to influence the direction of the project, - how to participate in discussions around the project, and ways you can make - a difference. I hope this article has inspired you to get involved with the - project, or has at least given you some idea on how things work and what you - can do if you ever do decide you want to get involved! + Below are some useful links for developers: + <ul> + <li><a href="http://lxr.php.net">lxr</a> - an online interface to the PHP source, providing search facilities useful for programmers and researchers</li> + <li><a href="https://wiki.php.net/rfc/howto">The RFC process</a> - the process by which developers can suggest and discuss new ideas with the community</li> + <li><a href="/build-setup">Developer Setup Help</a> - some helpful information regarding setting up a development environment for PHP</li> + </ul> </p> - - <?php site_footer(array('sidebar'=>$SIDEBAR_DATA));
diff --git a/build-setup.php b/build-setup.php new file mode 100644 index 0000000..790beb7 --- /dev/null +++ b/build-setup.php @@ -0,0 +1,167 @@ +<?php +// $Id$ +$_SERVER['BASE_PAGE'] = 'get-involved.php'; +include_once $_SERVER['DOCUMENT_ROOT'] . '/include/prepend.inc'; + +$SIDEBAR_DATA =' + <p> + This page is intended to help setup a development environment for PHP, if mistakes are found + please <a href="http://bugs.php.net">report</a> them. + </p> +'; + +site_header("Get Involved", array("current" => "community")); + +?> +<h2>Operating System Preparation</h2> +<p> + Improving PHP requires a working build environment to test changes, the following section deals with setting up a working build environment. +</p> +<p> + Your build environment should have an appropriate toolchain that includes a working C compiler, + for those not working in Microsoft Windows, you will need a working, compatible autotools installation, and at the very least a shared copy of zlib. +</p> +<p> + For most *nix like operating systems, some external dependencies may be required to bring a build to completion; + if a build fails because of missing headers or libraries, issuing a variant of the following command should resolve those dependencies, allowing the build to continue: + <ul> + <li>[sudo] yum|apt-get|ports install package[-dev[el]]</li> + </ul> +</p> +<p> + For those working in <i>Ubuntu Linux</i>, you can run the following command to automate the installation of dependencies: + <ul> + <li>sudo apt-get build-dep php5</li> + </ul> + If the compilation of <i>an extension</i> should fail because of missing dependencies, <i>Ubuntu Linux</i> can attempt to automate the resolution of those dependencies by issuing: + <ul> + <li>sudo apt-get build-dep php5-<i>extname</i></li> + </ul> +</p> +<p> + The following table shows what is required for Microsoft Windows users to build PHP: +<p/> +<table> +<tr> + <th>PHP</th> + <th>Visual C++</th> + <th>MS SDK</th> + <th>DEPS</th> + <th>PHP SDK</th> +</tr> +<tr> + <td align="center">5.3</td> + <td align="center">Visual Studio 2008</td> + <td align="center">6.1</td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/deps-5.3-vc9-x86.7z">x86</a></td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/php-sdk-binary-tools-20110512.zip">here</a></td> +</tr> +<tr> + <td align="center">5.4</td> + <td align="center">Visual Studio 2008</td> + <td align="center">6.1</td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/deps-5.4-vc9-x86.7z">x86</a></td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/php-sdk-binary-tools-20110915.zip">here</a></td> +</tr> +<tr> + <td align="center">5.5</td> + <td align="center">Visual Studio 2008</td> + <td align="center">6.1</td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/deps-5.5-vc9-x86.7z">x86</a></td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/php-sdk-binary-tools-20110915.zip">here</a></td> +</tr> +<tr> + <td align="center">5.5</td> + <td align="center">Visual Studio 2012</td> + <td align="center">N/A</td> + <td align="center"> + <a href="http://windows.php.net/downloads/php-sdk/deps-5.5-vc11-x86.7z">x86</a>, + <a href="http://windows.php.net/downloads/php-sdk/deps-5.5-vc11-x64.7z">x64</a> + </td> + <td align="center"><a href="http://windows.php.net/downloads/php-sdk/php-sdk-binary-tools-20110915.zip">here</a></td> +</tr> +</table> +<p><b>Note:</b> If a Windows SDK is required, it is advised to install the SDK <i>before</i> Visual Studio.</p> + +<h2>Workspace Preparation</h2> +<p> + Windows users should now download and unzip the PHP SDK to their workspace and execute the following commands in an appropriate Visual Studio Console: +</p> +<p> + Visual Studio 2008: + <ul> + <li>setenv /xp /Release /x86</li> + </ul> + Visual Studio 2008 and 2012: + <ul> + <li>cd C:\path-to-workspace</li> + <li>bin\phpsdk_setvars.bat</li> + <li>bin\phpsdk_buildtree.bat phpdev</li> + </ul> + Windows should now change to the directory C:\path-to-workspace\phpdev\<i>VCXX</i>\<i>XARCH</i>, and consider it the root of the workspace for the current build. +</p> +<p> + The next step for everyone is to obtain the versioned PHP sources via git: + <ul> + <li>git clone -b BRANCH https://github.com/php/php-src .</li> + </ul> + BRANCH should be replaced with an appropriate branch name, for example <i>PHP-5.5</i>. +</p> +<p> + At this point you have a working build environment and the vanilla sources for your chosen branch of PHP, it is a good idea, before you change anything at all, to create a new branch and switch to it, in preparation for your awesome changes to come: + <ul> + <li>git checkout -b my-awesome-changes</li> + </ul> +</p> +<h2>Building Your Development PHP</h2> +<p> + All operating systems now converge on (near as makes no difference) the same solutions for the rest of the build process: + <ul> + <li>buildconf: generates the configure script for PHP</li> + <li>configure: configures the build of PHP and creates Makefile</li> + <li>make: builds PHP</li> + <li>make test: runs testsuite</li> + <li>make install: installs PHP</li> + </ul> +</p> +<p> + For Microsoft Windows operating systems, those commands looks like this: + <ul> + <li>buildconf</li> + <li>configure --with-prefix=C:\my-awesome-php</li> + <li>nmake</li> + <li>nmake test</li> + <li>nmake install</li> + </ul> +</p> +<p> + While for the rest of us, those commands look like this: + <ul> + <li>./buildconf</li> + <li>./configure --prefix=/opt/my-awesome-php</li> + <li>make</li> + <li>make test</li> + <li>make install</li> + </ul> +</p> +<p> + The <i>configure</i> script has the ability to customize almost every aspect of PHP, to ellicit help at the console pass <i>--help</i> + as the only argument to <i>configure</i></p> +<p> + When <i>configure</i> executes, it saves the options passed in to a re-usable <i>config.nice</i> which executes <i>configure</i> when invoked. +</p> +<p> + Upon successful completion of a build, it is recommended to run the test suite, this will help you to identify regression problems in your work, + running the test suite can take a while; go out for a run, or a burger. +</p> +<p> + It is also possible to run a set (directory) of tests in the following way: + <ul> + <li>[n]make test TESTS=sapi/cli</li> + </ul> +</p> +<?php +site_footer(array('sidebar'=>$SIDEBAR_DATA)); + +/* vim: set et ts=4 sw=4 ft=php: : */ + diff --git a/get-involved.php b/get-involved.php index 1de2e43..f89d0ac 100644 --- a/get-involved.php +++ b/get-involved.php @@ -16,543 +16,42 @@ $SIDEBAR_DATA =' site_header("Get Involved", array("current" => "community")); ?> -<h2>Improving PHP</h2> +<h2>Contributing to PHP</h2> <p> - This particular article assumes you are running <i>Ubuntu Linux</i>. + Anybody who programs in PHP can be a contributing member of the community that develops and deploys it; + the task of deploying PHP, documentation and associated websites is a never ending one. + With every release, or release candidate comes a wave of work, which takes a lot of organization and co-ordination. </p> <p> - To get a working build environment you need to run the following command; - <ul> - <li>sudo apt-get build-dep php5</li> - </ul> -For any extension that requires 3rd party libraries you need to install those libraries. -The simplest way to accomplish that is to to use <em>apt-get</em> to install the Ubuntu build dependencies for that particular extension. For example, if you want to build PHP with <a href="/manual/intl">intl</a> support you have to run; - <ul> - <li>sudo apt-get build-dep php5<em>-intl</em></li> - </ul> -to install the ext/intl dependencies. -</p> -<p> -To actually build PHP with ext/intl support you need to configure PHP to enable it, f.e. - <ul> - <li>./configure --enable-intl</li> - </ul> - The rule of thumb for configuring PHP is;<br /> - <ul> - <li>If its a pure PHP functionality use <em>--enable</em>extension-name<br /> - Example; - <ul> - <li>./configure --enable-soap</li> - </ul> - </li> - <li>And for extensions wrapping external libraries use <em>--with</em>-extension-name<br /> - Example; - <ul> - <li>./configure --with-pgsql</li> - </ul> - </li> - </ul> - But as you saw with ext/intl, rules are meant to be broken - so you <em>should</em> check <i>./configure --help</i> first.<br /> - When PHP encounters unknown configure argument you will be notified in the end, so you can modify your arguments and re-run ./configure before executing <em>make</em>. -</p> -<p> -PHP creates a script called <em>config.nice</em> after every successful <em>./configure --some --arguments</em> so you don't have to remember all the options you passed to ./configure every time you want to rebuild PHP, running <em>./config.nice</em> will do that for you -</p> - -<p> -Once you have the build dependencies installed you'll need to checkout PHP from Git, configure and build it; -<ul> - <li>git clone -b PHP-5.4 http://git.php.net/repository/php-src.git php-5.4</li> - <li>cd php-5.4</li> - <li>./buildconf</li> - <li>./configure (see the <a href="#config.nice">shell script helper below)</a></li> - <li>make all test</li> -</ul> -</p> - -<p>While `make all test` is running we recommend you go out for a run, -it can take a while. When you come back, submit -the test results, but then try to track down one of the failed tests and -figure out why it failed. The tests are very simple. In the failed test -summary at the end a failed test shows up as:<br /> -<em>CLI php -m [sapi/cli/tests/018.phpt]</em> -<br /> -That's a short description of the test and the filename of the test itself. -For a failed tests, we create some files in the test dir. Go to sapi/cli/tests -and you will find these files: -<ul> - <li>018.phpt - the full test file</li> - <li>018.php - the php code that was run for the test</li> - <li>018.out - the actual output from the test</li> - <li>018.exp - the output that we expected</li> - <li>018.diff - the diff between the actual and expected</li> -</ul> -Once you have fixed something, you can re-run the tests for just that set of -tests with: -<ul> - <li>make test TESTS=sapi/cli</li> -</ul> -</p> -<p> -To run more tests, run ./configure and enable as many extensions as possible. -</p> -<p id="config.nice"> -Here is the shell script I use on an Ubuntu box: -<pre> -#! /bin/sh -'./configure' \ -'--with-apxs2=/usr/bin/apxs2' \ -'--with-curlwrappers' \ -'--with-gd' \ -'--with-jpeg-dir=/usr' \ -'--with-png-dir=/usr' \ -'--with-vpx-dir=/usr' \ -'--with-freetype-dir=/usr' \ -'--with-t1lib=/usr' \ -'--enable-gd-native-ttf' \ -'--enable-exif' \ -'--with-config-file-path=/etc/php5/apache2' \ -'--with-config-file-scan-dir=/etc/php5/apache2/conf.d' \ -'--with-mysql=/usr' \ -'--with-zlib' \ -'--with-zlib-dir=/usr' \ -'--with-gettext' \ -'--with-kerberos' \ -'--with-imap-ssl' \ -'--with-mcrypt=/usr/local' \ -'--with-iconv' \ -'--with-ldap=/usr' \ -'--enable-sockets' \ -'--with-openssl' \ -'--with-pspell' \ -'--with-pdo-mysql=/usr' \ -'--with-pdo-sqlite' \ -'--enable-soap' \ -'--enable-xmlreader' \ -'--with-xsl' \ -'--enable-ftp' \ -'--enable-cgi' \ -'--with-curl=/usr' \ -'--with-tidy' \ -'--with-xmlrpc' \ -'--enable-mbstring' \ -'--enable-sysvsem' \ -'--enable-sysvshm' \ -'--enable-shmop' \ -'--with-readline' \ -'--with-mysqli=/usr/bin/mysql_config' \ -'--prefix=/usr/local' \ -"$@" -</pre> -<p> -There are also README.TESTING and README.TESTING2 text files in the root -directory if you want to learn more about the testing mechanism. -</p> - - -<hr /> - -<h2>Contributing</h2> -<p> - The PHP project is so much more than just the scripting language on which it is - focused. It is a vibrant community of developers scratching related itches, - hoping their work will benefit others. PHP.net hosts a set of projects - focused around the "flagship product," the PHP language, surrounding it - with sub-projects for documentation, website maintenance, adding extra - functionality with extensions, and so on. -</p> - - -<p> - The PHP community is without a doubt, in my opinion, one of the greatest - communities in the world. It has a lot to offer besides good friends and a fun - working environment. It is a community where things can happen very fast, with - many people involved, contributing back "upstream" to PHP in various - capacities, from user-contributed notes to the manual to new killer language - features. There is always room for new contributors though, and PHP.net really - needs your help so it can continue the success of past years. In this article - we will explore how the PHP.net project works and how you can contribute to it. + With the introduction of release managers comes a smooth release process, but still help is needed: + testing release candidates, finding and squishing bugs in tests, documentation, and sources. </p> - +<h3>Four Best Ways to Contribute</h3> <p> - There are a lot of ways in which you can contribute to and influence the project; - participating on mailing lists, filing bug reports, and adding helpful notes - to the manual are all examples of valuable contributions. You don't have to - develop a new JIT compiler, or even know the first thing of - developing a language for that matter, to be able to contribute back. Whatever - you fancy, I am sure you can find a challenging task on PHP.net to solve. Or - are you maybe just looking for some brain-dead task on which to spend time - - but still want to make a difference? We have several of those too! + <ol> + <li>Running test suites in <a href="http://qa.php.net/">RC</a> and <a href="http://php.net/releases">release</a> distributions of PHP</li> + <li>Help finding and diagnosing failed tests <a href="http://qa.php.net/write-test.php">phpt documentation</a></li> + <li>Filing and resolving bug reports at <a href="http://bugs.php.net">bugs.php.net</a></li> + <li>Help maintain and or translate documentation files at <a href="http://edit.php.net">edit.php.net</a></li> + </ol> </p> - - +<h3>Development of the PHP source</h3> <p> - Before we go deeper into ways you can contribute and how to do so, let's take - a step back and look at who actually leads the development and how things are - done within PHP.net. + Someone hoping to become involved in the maintanence and development of the source should be experienced in all of the areas mentioned above, + this creates a strong team; everyone knows how every other part of the project works. </p> - - <p> - One of things I love most about working with Open Source Software like PHP is - the freedom. If I have an itch, I scratch it! If I want to work on new - features or document all the kinks and quirks of PHP, I can. We have the - freedom to work on exactly the things we care about and want to do. - There is no one person in charge or policing of the project, it is a community - effort. All decisions are made in the open after the contributors - participating in the discussion reach "general consensus" on the topic or - if - all else fails - after a vote on the subject. As within any community, there; - are members that have earned karma and respect through contributions to the - project, and their meaning and views usually carry more weight than a total - stranger from whom no one has heard before. Karma, like trust, needs to be - earned. + You will also need experience in C programming as PHP is written entirely in C. </p> - - -<p> - To gain karma you basically need to prove to the community that you aren't - just a nut-job and show that you can be trusted to think not only about today, - but tomorrow as well. Being active on the developers' mailing lists, - digging into bug reports, posting patches and unit tests, and generally - trying to help out and contribute to the project are great ways to gain a - lot of karma points very quickly. -</p> - - -<p> - All of the PHP.net projects (from PEAR, to PECL, to websites and - documentation, to the PHP language itself) have - long-time members which could be considered the "leaders" of the respective - projects by the community, but that really doesn't mean anything other than - "if no one knows the answer, ask him." The "leader" isn't going to tell you to - do anything, other than maybe ask you to revert a bad commit, but anyone can - do that. It is totally up to you to decide whether or not to work on some - things. In the end, the final say on the matter is up to the contributor who - is actually doing the work. -</p> - - <p> - The PHP.net project has mailing lists for most aspects of the project where - all important decisions are made. For example discussions and decisions about - the language happen on the internals@lists.php.net mailing list - (internals-win@lists.php.net for Windows-specific things such as packaging, - porting features not available yet on Windows, et cetera). All discussions - are open to whomever wants to participate. All you need to do is to sign up - to the mailing list and follow the discussions - and chime in if you have - something to add. Please take a few moments to familiarize yourself with the - mailing list "rules" before you go all crazy on the lists. For the rules that - are generally followed on all PHP mailing lists, please see the - <a href="http://php.net/reST/README.MAILINGLIST_RULES">Mailinglist Rules</a>. -</p> - - -<p> - Although most of the PHP internals contributors make their living writing PHP - applications, feedback from other users is crucial to the development of the - language; your voice does matter. Keep in mind, however, that flaming - and/or talking down to the developers that spend most of their free time - working on the project may not exactly be the best approach to get your point - across. Take a look at the <a href="http://php.net/mailinglists">Mailing Lists</a> for the most - popular mailing lists and see if any of them interest you, then sign up! -</p> - - -<p> - Even though most of the mailing lists are very active, not everything that is - contributed to PHP needs to be approved there first. For example, minor - features are often simply committed directly to Git without asking or telling - anyone. These are typically things for which a developer working on an - external application saw a need and decided to add, in case anyone else might - need it in the future. PHP has a great peer review process so it's very hard - to "sneak" things in. Every commit to Git is reviewed by quite a lot of people - who are interested in what is going on - or who simply enjoy reading code. If - a reviewer discovers issues with the commit, he or she will send a quick reply - to the commit email and discuss it on the developers list. Often the peer review - results in extending the new feature and/or fixing unexpected behaviour, but - it can also result in removal of the feature as a whole if the community - doesn't see any need for it. -</p> - - -<p> - To help streamline part of the decision process and keep track of ideas, - proposals, and TODO lists, PHP has a wiki located at - <a href="http://wiki.php.net">wiki.php.net</a>. This has proven to be a valuable resource when - developing new features, creating RFCs, and getting approval for things - before wasting time on a rejected feature. Discussions on controversial - features pop up on the mailing lists regularly, but with the help of the - wiki people can easily browse through previous discussions and see the - reasons for rejection. The wiki contains a lot of great information and is - definitely worth browsing for all those interested in the overall PHP.net - project. It not only covers RFCs, but also has a lot of information about - how various other things work; missing documentation, suggestions, - "internal" parser engine information, infrastructure docs, and even some - TODO lists are all examples of things included in the wiki. -</p> - - - - -<h3>So, how to get involved?</h3> -<p> - There are a lot of ways you can contribute to the project, it simply depends on what you fancy. -</p> -<ul> - <li> - Do you want to work on UI design, or general website development? - Looking for a place to experiment with emerging web technologies? We have - several websites, both 'internal' and external, many of which could use a - facelift, while others, quite frankly, could benefit from a complete - rewrite. - </li> - <li> - Do you enjoy technical writing? Discovering the inner workings of things? - Being the first one to try out not-even-yet-released features? Join the - documentation team. Having a good understand of C will help when documenting - new features, but there will always be people around to explain features to - whomever wants to document them. - </li> - <li> - Want to show off your sysadmin skillz? PHP.net has dozens of servers - needing some love. Everything from simple web servers to complicated mail - setups, DNS and rsync servers to build-boxes and website mirroring - infrastructure. - </li> -</ul> - -<p> - Getting involved is a lot easier than most people think - and chances are that - you are already involved in one way or another. You don't need an Git account - and commit access to get started - Git accounts need to be earned. Registering - on the mailing lists related to the topic in which you are interested - and - actively participating in the discussions - is a good start toward getting - your request for an Git account granted. Browse the wiki to see if there are - outstanding TODO items you can help to clear, for example. Another great way - to get involved and really help out is by reviewing the bug tracker for bugs - you could potentially fix, or perhaps for which you could write a unit test. - Sending several pull requests, or attaching patches to bug reports will - quickly show that you are interested and serious about your desire to - contribute. Eventually someone will get annoyed with the amount of time - they must spend to commit your patches for you, and will probably respond - with something along the lines of, "Stop bothering me. Do it yourself!" and - ask you to submit the Git account form. Mission accomplished! -</p> - - - - -<h3>Tips</h3> -<ul> - <li> - <h4>Mailing Lists</h4> - <p> - To register with any PHP mailing list, just send a blank email to - <listname>-subscribe@lists.php.net. For example if you want to register - for the PHP internals developers discussion list, send an email to - internals-subscribe@lists.php.net. - Alternatively, filling out the form at <a href="http://php.net/mailinglists">php.net/mailinglists</a> will - register you for the list (or lists) you choose. That page also lists some of - the most popular mailing lists and describes the intention of the lists. - Again, remember to refer to the rules prior to joining the discussion, or you - may be scorned for a faux-pas such as top-posting your reply to a thread - oh the horror! - </p> - </li> - <li> - <h4>The Bug Tracker</h4> - <p> - Filing a bug report is an art. It isn't very complicated, but you do - have to think about what you are reporting. Quickly looking through - the existing reports to see if your issue has already been reported - will take you less than five minutes, and the chances are quite good that - you aren't the first one to identify the issue. However, if you are, - we greatly appreciate your time and effort in reporting it. If at all - possible, provide a short example of how the issue can be reproduced, - and mention what you expected to happen versus what actually happened. - Simple steps like these will drastically increase the chances of - someone picking up the report and attempting to fix the issue. While - there is no registration or login required to file a bug report, a - valid email address must be provided just in case the developers need - more information from you, as well as for you to receive status - updates on your report. A page explaining how to file a "report that - someone will want to help fix" is available on - <a href="http://bugs.php.net/how-to-report.php">bugs.php.net/how-to-report.php</a>. Please read through it - before filing a bug report for the first time. - </p> - </li> - <li> - <h4>Getting Started With Contributing</h4> - <p> - Unsure which task to tackle first? Stuck on a problem? Need a - quick brainstorming session? IRC is a very convenient way to get - help quickly for smaller things, such as "where was the Git module - for zyx?" or if you simply want to run an idea by people to get - their opinions - or even just to hang out. There aren't any - "official" IRC channels for the PHP project, but a good chunk of - contributors hang out on EFNet on the #php.pecl, #php.doc and #pear - channels. The mailing list archives also contain a lot of information - and are definitely worth searching for ideas and inspiration. If - you think your question can benefit others coming after you, - consider asking it on the mailing list so the next person doesn't - have to ask it again. - </p> - </li> - <li> - <h4>Less Is More</h4> - <p> - When you are ready to contribute to the project please don't try - to tackle the biggest issues and expect to fix them right away. - Start with smaller tasks and learn the ways of the project and - participate in discussions on the mailing lists. Larger issues - take more time and experience within the project, which is not - something on which newcomers should focus. Take your time and - solve the task as best as you possibly can. Read up on the Coding - Standards and try to be consistent in your work. We have lost too - many people who jump right on the larger tasks only to vanish few - days later, having given up on the task because it took more time - and effort than they initially anticipated. - </p> - </li> -</ul> - - - -<h3>So what kind of projects does PHP.net have?</h3> -<ul> - <li>PHP (the language)</li> - <li>PECL (various additional PHP functionality in the form of extensions)</li> - <li>PEAR (reusable PHP component library)</li> - <li>Websites (php.net, qa.php.net, doc.php.net, edit.php.net, etc.)</li> - <li>Documentation (PHP, PECL, PEAR, etc.)</li> - <li>System administration (mail servers, web servers, build-boxes, monitoring, etc.)</li> - <li>Etc., etc., (etc.)</li> -</ul> - -<p> - If you can't find something on which to work within PHP.net, you will have a - hard time finding it elsewhere. Introducing every project is beyond the scope - of this article, but we'll cover some of the projects that don't have entry - points that are too steep for newcomers. -</p> - - - -<h3>The Documentation Project</h3> -<p> - The main focus of the documentation project (phpdoc) is to document the PHP - language (and PECL extensions) with usage examples, FAQs, and tracking changes - in behaviour. The documentation is written in XML using the Docbook format - with English as the primary language. This is then translated into several - different languages by dedicated translation teams. The phpdoc team also - maintains sets of scripts to simplify the work: generation of skeletons for - new extensions and functions based on Reflection information, extracting INI - options, and various related utilities to extract information from the PHP - source code are all examples of tools used to make writing documentation - easier. The primary mailing list for phpdoc is phpdoc@lists.php.net, where - contributors coordinate their efforts and ask for feedback, suggestions, and - help. The list also covers the phpdoc sub-projects, such as the PhD and PhD - O.E. applications. Each translation team also has its own mailing list: - doc-<country-code>@lists.php.net. For example, doc-fr@lists.php.net for - the French translation list. -</p> - -<p> - A web application, called "PhD Online Editor" (PhD O.E), which aims to help - documentation editors focus on the content itself, rather than Docbook and XML - logistics, is under development at <a href="https://edit.php.net">edit.php.net</a>. It is getting - more and more popular, especially for newcomers who aren't comfortable with - Docbook. It has a very rich interface and desktop application feeling to it, - and abstracts most of the XML magic from the contributor. One of the goals - of PhD O.E. is to get more people involved with the documentation effort, - and therefore it will allow anonymous users to "login" and use the - application. Modification, validation, translation, creation of new files, - and everything else you need for writing documentation is possible without - an Git account. When saving changes, a patch will be created and saved to - the "patch queue," while pending approval by someone with Git karma to - commit the changes. PhD O.E. also bundles a variety of scripts to ensure the - docs use a consistent structure, allow the contributor to view undocumented - functions, and check the translation status of an entry (among other things). -</p> - -<p> - The team is also developing a Docbook rendering engine, called "PHP-based - Docbook Rendering" (PhD), to transform the Docbook XML into various different - formats, such as HTML, CHM, PDF, Unix manual pages, and the online format you - see while browsing the <a href="http://php.net/manual">PHP Manual</a>. The application was written with - performance in mind and can render the entire PHP manual in less then five - minutes, whereas the previous tool chain would take over an hour for the same - task. PhD has received a lot of attention from various people and projects - using Docbook, and is now also in use outside of PHP.net for the rendering of - Docbook manuals. -</p> - - -<p> - Last, but not least: the team also maintains a website on - <a href="http://doc.php.net">doc.php.net</a> which aggregates translation - statistics, tutorials, and the documentation HOWTO. -</p> - -<p> - The project offers much more than just documentation, and is probably the - project to which it is easiest to start contributing. If you enjoy working - with XML, PHP, JS, documentation, writing articles, or simply want to dig - into the PHP internals from a different angle, this is the place to be. -</p> - - -<h3>The Websites</h3> -<p> - No surprise there, the webmaster team maintains several websites, and is - responsible for maintaining the mirroring infrastructure and related tasks. - The websites contain a lot of information; everything from user group meet-ups - and conference listings, to tips & tricks and documentation, and - everything between. It is also the primary public source for release - information, as well as the general entry point for people looking into PHP. -</p> - -<p> - To get up and running is very simple: just follow the points on - <a href="http://wiki.php.net/web/mirror">wiki.php.net/web/mirror</a> - and you are all set. Once you have poked around a little you can look - into the other websites, like qa.php.net, master.php.net and pecl.php.net. -</p> - -<p> - Recently, work on redesigning the main website from the ground-up was started. - Unfortunately, this effort has stalled a bit over the past several months - due to a lack of contributors interested in being actively involved. - The idea is simple: design a completely new layout and refactor the current - content to make it more accessible. -</p> - -<p> - Joining the redesign effort is a great entry point for those interested in - markup, CSS, and general website development. Check out - <a href="http://wiki.php.net/web/redesign">wiki.php.net/web/redesign</a> - and contact php-webmaster@lists.php.net if you are interested in contributing. - You will be welcomed with roses! -</p> - - - -<h3>Conclusion</h3> -<p> - PHP.net has a lot of areas to which you can contribute: everything from - hardcore development to managing user-contributed notes in the manual; - from debugging issues in bug reports to writing articles about new features - for the manual. In this article we only covered the tip of the iceberg, - mentioning only a small sample of concrete projects that do a lot more than - initially meets the eye, and which welcome all the help they can get. - We have also touched on how to influence the direction of the project, - how to participate in discussions around the project, and ways you can make - a difference. I hope this article has inspired you to get involved with the - project, or has at least given you some idea on how things work and what you - can do if you ever do decide you want to get involved! + Below are some useful links for developers: + <ul> + <li><a href="http://lxr.php.net">lxr</a> - an online interface to the PHP source, providing search facilities useful for programmers and researchers</li> + <li><a href="https://wiki.php.net/rfc/howto">The RFC process</a> - the process by which developers can suggest and discuss new ideas with the community</li> + <li><a href="/build-setup">Developer Setup Help</a> - some helpful information regarding setting up a development environment for PHP</li> + </ul> </p> - - <?php site_footer(array('sidebar'=>$SIDEBAR_DATA));