PHP Wiki doc:articles

doc:articles:newtranslation

2008-05-28T06:10:05+00:00

1210467011		current
Line 8:		Line 8:
	* Update CVSROOT/modules		* Update CVSROOT/modules
	* Update CVSROOT/loginfo		* Update CVSROOT/loginfo
		+	* Update CVSROOT/avail (in a couple places)
	* Add {lang} to docweb for revcheck		* Add {lang} to docweb for revcheck
	* Add {lang} to phpweb/includes/languages.inc as INACTIVE		* Add {lang} to phpweb/includes/languages.inc as INACTIVE
	* Add the new {lang} mailing list to our super secret gmail doc account (user php.doc.lists)		* Add the new {lang} mailing list to our super secret gmail doc account (user php.doc.lists)

doc:articles:nomenclature

2008-03-11T03:43:48+00:00

1205111489		current

doc:articles:updating-markup

2009-03-24T17:03:36+00:00

1234824133		current
Line 1:		Line 1:
-	Updating PHP docs to the new markup	+	==== Updating PHP docs to the new markup ====

	Several PHP extensions have documentation for OO-style APIs which is written as if the documentation was a procedural API. A good example of this was ext/soap, but also ext/rar seems to be using the old markup too. So, I'm going to take this as my example. If you go to http://php.net/rar, and look over the methods of the Rar class, you can see they're documented just the same as the functions rar_close(), rar_entry_get(), etc. This isn't handy and makes the search less useful. There is a new variant of the DocBook markup which makes more sense for OO APIs, and it should be converted. This is basically a copy and paste job.		Several PHP extensions have documentation for OO-style APIs which is written as if the documentation was a procedural API. A good example of this was ext/soap, but also ext/rar seems to be using the old markup too. So, I'm going to take this as my example. If you go to http://php.net/rar, and look over the methods of the Rar class, you can see they're documented just the same as the functions rar_close(), rar_entry_get(), etc. This isn't handy and makes the search less useful. There is a new variant of the DocBook markup which makes more sense for OO APIs, and it should be converted. This is basically a copy and paste job.
Line 39:		Line 39:

	TODO: Describe fixing user notes.		TODO: Describe fixing user notes.
		+	TODO: Describe how to deal with old CVS history... links to old files should be in the commit message at least.

doc:articles:whitespace

2008-03-10T01:48:01+00:00

	current
Line 1:	Line 1:
	+	====== Why we care about whitespace ======
	+	I just wanted to post a little reminder about why we care so much about whitespace. Over the years this topic has come up in many forms, usually via a whitespace unfriendly commit that is immediately followed by a fellow team members complaint. And soon after, a fix is made. There are reasons we as a group (especially all past and present editors) have been strict and anal about this topic and here's why:

	+	==== Consistent look to the documentation ====
	+	All the documentation ends up looking the same within all editors. The indention here is one space, no tabs, and only PHP code itself is four spaces as per our coding standards. This is a beautiful and consistent feature of the PHP manual sources.
	+
	+	==== Pretty diffs ====
	+	Peer review is critical to the success of any Open Source project, including the PHP Manual. Fellow members of the team follow and read the commits so a diff should focus on changed content and not mix in whitespace manipulations. If something doesn't fit or look right, our eyes focus on it... this wastes time. Translators also rely on pretty diffs.
	+
	+	==== Diff === Artistic Masterpiece ====
	+	Each diff can be seen as a piece of art. Look it over... is this something you might send your lover? Professor? Potential employer? Remember that every commit we make goes on record forever and represents the author. Making them pretty and useful means we will be pretty and useful, both individually and as a group.
	+
	+	==== A Diff should be perfect ====
	+	Sometimes we want to quickly commit something and if needed update it again later. This is no good and instead we should wait until later before making the commit. There is no need to spam the mailing list with "I didn't have time and was going to fix it later" commits... there is no rush, the manual has existed for 10 years without the information and can wait another hour/day... simply save the file and attend to it later. The perfect diff meets all of the above descriptions.
	+
	+	====== How to create pretty whitespace =====
	+	Unified diffs make this easy. Before any commit is made, the author should look over a diff of the edited file(s). This allows said author to find errors (like typos) as well as accidental whitespace changes. After making another change, check it again. Once the diff is as intended then commit it (after make test of course!) and move on.
	+
	+	I hope this helps explain why we are so strict about whitespace.

doc:articles:writing-tests

2008-04-10T22:58:24+00:00

1207866469		current
Line 1:		Line 1:
	Part of an upcoming php.net article titled "How can you help PHP.NET today?" with this part focusing on writing tests. It's essentially in a FAQ format:		Part of an upcoming php.net article titled "How can you help PHP.NET today?" with this part focusing on writing tests. It's essentially in a FAQ format:

-	* Why should I write a test?	+	===== Why should I write a test? =====
	Code coverage is important for the success of any project including PHP. When code coverage reaches 100%, it'll mean that every piece of code within the PHP sources will be executed while running the tests. This helps determine if behaviour changes so essentially it helps prevent bugs from being introduced into PHP.		Code coverage is important for the success of any project including PHP. When code coverage reaches 100%, it'll mean that every piece of code within the PHP sources will be executed while running the tests. This helps determine if behaviour changes so essentially it helps prevent bugs from being introduced into PHP.

-	* What kind of setup do I need to write good tests?	+	===== What kind of setup do I need to write good tests? =====
	gcc >= 3.4 with gcov.		gcc >= 3.4 with gcov.
	Your local setup should also include lcov that is available here:		Your local setup should also include lcov that is available here:
Line 23:		Line 21:
	In summary: Install lcov, compile PHP with --enable-gcov, and now you're ready.		In summary: Install lcov, compile PHP with --enable-gcov, and now you're ready.

-	* How do I find what needs a test?	+	===== How do I find what needs a test? =====
	* Go to gcov.php.net		* Go to gcov.php.net
	* Choose a branch, then 'coverage'		* Choose a branch, then 'coverage'
	* Will go into some detail on what it means		* Will go into some detail on what it means

-	* How do I create a test?	+	===== How do I create a test? =====
	* Go to http://qa.php.net/...		* Go to http://qa.php.net/...

-	* Do you have a good example of a test and what it covers?	+	===== Do you have a good example of a test and what it covers? =====
	* Yes...		* Yes...

-	* How do I cover uncovered code?	+	===== How do I cover uncovered code? =====
	* Locate a file with a percentage < 100%		* Locate a file with a percentage < 100%
	* Use the legend to determine uncovered code		* Use the legend to determine uncovered code
	* Write code that will execute it		* Write code that will execute it
-	*

-	* How do I determine if the desired code gets executed?	+	===== How do I determine if the desired code gets executed? =====
	* make lcov		* make lcov
	* view lcov_html/index.html		* view lcov_html/index.html
Line 48:		Line 45:
	* Note: The TESTS var is to speed-up the process, as it will only run the specific test(s)		* Note: The TESTS var is to speed-up the process, as it will only run the specific test(s)

-	* How and where do I submit my test?	+	===== How and where do I submit my test? =====
	You can submit tests to the development mailing list @ internals@lists.php.net		You can submit tests to the development mailing list @ internals@lists.php.net

-	* What is open-box and black-box testing and why do I care?	+	===== What is open-box and black-box testing and why do I care? =====

-	* Do I need valgrind? When and why might I use it?	+	===== Do I need valgrind? When and why might I use it? =====
	Short answer: You don't.		Short answer: You don't.
	Long answer: valgrind can be used to detect if some test triggers a memory-related bug in PHP. Although running the test suite with valgrind is a plus, but it takes ages. You can submit tests without running valgrind, because the http://gcov.php.net project will do that for you.		Long answer: valgrind can be used to detect if some test triggers a memory-related bug in PHP. Although running the test suite with valgrind is a plus, but it takes ages. You can submit tests without running valgrind, because the http://gcov.php.net project will do that for you.

-	* How do I install lcov on Linux, Mac, and/or Windows? What part of the package do I need?	+	===== How do I install lcov on Linux, Mac, and/or Windows? What part of the package do I need? =====
-		+	Just untar it and run make install.
-	just untar it and run make install.	+