From 836725ee4d0c8589140922a8f05a0a9a2089ea4e Mon Sep 17 00:00:00 2001 From: krakjoe Date: Tue, 17 Sep 2013 22:37:01 +0100 Subject: [PATCH] changes to get-involved and introduce build-setup --- build-setup.php | 167 ++++++++++++++ get-involved.php | 561 +++-------------------------------------------- 2 files changed, 197 insertions(+), 531 deletions(-) create mode 100644 build-setup.php diff --git a/build-setup.php b/build-setup.php new file mode 100644 index 000000000..790beb7b4 --- /dev/null +++ b/build-setup.php @@ -0,0 +1,167 @@ + + This page is intended to help setup a development environment for PHP, if mistakes are found + please report them. +

+'; + +site_header("Get Involved", array("current" => "community")); + +?> +

Operating System Preparation

+

+ Improving PHP requires a working build environment to test changes, the following section deals with setting up a working build environment. +

+

+ 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. +

+

+ 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: +

+

+

+ For those working in Ubuntu Linux, you can run the following command to automate the installation of dependencies: +

+ If the compilation of an extension should fail because of missing dependencies, Ubuntu Linux can attempt to automate the resolution of those dependencies by issuing: + +

+

+ The following table shows what is required for Microsoft Windows users to build PHP: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PHPVisual C++MS SDKDEPSPHP SDK
5.3Visual Studio 20086.1x86here
5.4Visual Studio 20086.1x86here
5.5Visual Studio 20086.1x86here
5.5Visual Studio 2012N/A + x86, + x64 + here
+

Note: If a Windows SDK is required, it is advised to install the SDK before Visual Studio.

+ +

Workspace Preparation

+

+ Windows users should now download and unzip the PHP SDK to their workspace and execute the following commands in an appropriate Visual Studio Console: +

+

+ Visual Studio 2008: +

+ Visual Studio 2008 and 2012: + + Windows should now change to the directory C:\path-to-workspace\phpdev\VCXX\XARCH, and consider it the root of the workspace for the current build. +

+

+ The next step for everyone is to obtain the versioned PHP sources via git: +

+ BRANCH should be replaced with an appropriate branch name, for example PHP-5.5. +

+

+ 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: +

+

+

Building Your Development PHP

+

+ All operating systems now converge on (near as makes no difference) the same solutions for the rest of the build process: +

+

+

+ For Microsoft Windows operating systems, those commands looks like this: +

+

+

+ While for the rest of us, those commands look like this: +

+

+

+ The configure script has the ability to customize almost every aspect of PHP, to ellicit help at the console pass --help + as the only argument to configure

+

+ When configure executes, it saves the options passed in to a re-usable config.nice which executes configure when invoked. +

+

+ 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. +

+

+ It is also possible to run a set (directory) of tests in the following way: +

+

+$SIDEBAR_DATA)); + +/* vim: set et ts=4 sw=4 ft=php: : */ + diff --git a/get-involved.php b/get-involved.php index 1de2e43bb..f89d0ac48 100644 --- a/get-involved.php +++ b/get-involved.php @@ -16,543 +16,42 @@ $SIDEBAR_DATA =' site_header("Get Involved", array("current" => "community")); ?> -

Improving PHP

+

Contributing to PHP

- This particular article assumes you are running Ubuntu Linux. + 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.

- To get a working build environment you need to run the following command; + 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. +

+ +

Four Best Ways to Contribute

+

+

    +
  1. Running test suites in RC and release distributions of PHP
    2. +
  2. Help finding and diagnosing failed tests phpt documentation
    3. +
  3. Filing and resolving bug reports at bugs.php.net
    4. +
  4. Help maintain and or translate documentation files at edit.php.net
    5. +
+

+

Development of the PHP source

+

+ 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. +

+

+ You will also need experience in C programming as PHP is written entirely in C. +

+

+ Below are some useful links for developers:

-For any extension that requires 3rd party libraries you need to install those libraries. -The simplest way to accomplish that is to to use apt-get to install the Ubuntu build dependencies for that particular extension. For example, if you want to build PHP with intl support you have to run; - -to install the ext/intl dependencies.

-

-To actually build PHP with ext/intl support you need to configure PHP to enable it, f.e. -

- The rule of thumb for configuring PHP is;
- - But as you saw with ext/intl, rules are meant to be broken - so you should check ./configure --help first.
- 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 make. -

-

-PHP creates a script called config.nice after every successful ./configure --some --arguments so you don't have to remember all the options you passed to ./configure every time you want to rebuild PHP, running ./config.nice will do that for you -

- -

-Once you have the build dependencies installed you'll need to checkout PHP from Git, configure and build it; -

-

- -

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:
-CLI php -m [sapi/cli/tests/018.phpt] -
-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: -

-Once you have fixed something, you can re-run the tests for just that set of -tests with: - -

-

-To run more tests, run ./configure and enable as many extensions as possible. -

-

-Here is the shell script I use on an Ubuntu box: -

-#! /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' \
-"$@"
-
-

-There are also README.TESTING and README.TESTING2 text files in the root -directory if you want to learn more about the testing mechanism. -

- - -
- -

Contributing

-

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

- - -

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

- - -

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

- - -

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

- - -

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

- - -

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

- - -

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

- - -

- 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 - Mailinglist Rules. -

- - -

- 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 Mailing Lists for the most - popular mailing lists and see if any of them interest you, then sign up! -

- - -

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

- - -

- To help streamline part of the decision process and keep track of ideas, - proposals, and TODO lists, PHP has a wiki located at - wiki.php.net. 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. -

- - - - -

So, how to get involved?

-

- There are a lot of ways you can contribute to the project, it simply depends on what you fancy. -

- - -

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

- - - - -

Tips

- - - - -

So what kind of projects does PHP.net have?

- - -

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

- - - -

The Documentation Project

-

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

- -

- 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 edit.php.net. 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). -

- -

- 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 PHP Manual. 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. -

- - -

- Last, but not least: the team also maintains a website on - doc.php.net which aggregates translation - statistics, tutorials, and the documentation HOWTO. -

- -

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

- - -

The Websites

-

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

- -

- To get up and running is very simple: just follow the points on - wiki.php.net/web/mirror - 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. -

- -

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

- -

- Joining the redesign effort is a great entry point for those interested in - markup, CSS, and general website development. Check out - wiki.php.net/web/redesign - and contact php-webmaster@lists.php.net if you are interested in contributing. - You will be welcomed with roses! -

- - - -

Conclusion

-

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

- - $SIDEBAR_DATA));