Tag Archives: wordpress

WordPress Testing Presentation Video

Posted by Jacob Santos on April 13, 2008 2 comments

Critique of Myself

Crap.

I think I found some things out watching the video:

  1. I should take Johnathon Bailey’s advice and do like he does when giving a presentation. He’s rocked, mine was barely passable.
  2. I need to lose weight, so that I don’t have to pause to breath every other two words or so.
  3. You don’t need to look at the projected screen, when what is on the screen is right in front of you. I kicked myself as I was doing it, “Why are you looking at the screen self? It is right in front of you!” However, it probably isn’t something I can fix.

It is funny, I don’t remember taking as many pauses, I remember a few because I had to double check my notes on where I was at and what I needed to cover, but damn, the monotony makes me bored just listening to myself. There were a couple of times when I said a sentence without pausing, but probably only once or twice.

I had a similar problem the first couple of times I was on the WordPress Weekly Podcast. I couldn’t get my words out, but at least I didn’t stutter and say, “Um” more than probably three or four times. I find that I’m so used to making hand movements, when I speak that I can’t talk without them. I’m conducting myself speak.

Answering John P’s Question

I also have problems with either… or questions, as John P found out. I can hear my co worker now:

“Exactly.” I replied.
“It was an either… or question, so you have to choose one or the other.” said my mind bringing up a memory from several months ago.

To answer John’s question:

The Automattic WordPress Tests will allow a user to download, run the tests, and see which parts of WordPress is going to break. This, I envision, will shorten support time, decrease the scope of support questions, and improve the user outlook of WordPress. Instead of asking many questions about the host, the server configurations, PHP configurations, and asking the user to try many different techniques, the first support answer will be to download the WordPress Automated Tests and run it to see what breaks in WordPress and report back.

The amount of failures will be different on most users servers, so perhaps Alex and the other contributors don’t see any failures, which would be a good thing. Sending them the failure report or going to that web site which runs my tool will be able to drill down solutions and patches for fixing the problem the user is having.

This assumes that there is at least 80% code coverage with the test suites of the WordPress Library. RIght now, it would be difficult to say, “Just download this and run it,” until that point in the future when above 80% code coverage has been achieved.

So yes, as a user, you will be able to in the future, download the Automattic WordPress Tests and run it to see what breaks and find out how well your host supports WordPress. The Automattic WordPress Tests also has to be easier to install and run.

Why patch_cron.php?

What happens is that the wp-cron.php checks for wp-config.php on the base folder. So this means that there needs to be a wp-config.php in the folder that you are executing WordPress. This is the reason why the Automattic WordPress Tests requires that you create the wp-config.php in the folder that run-tests.php is in.

My Presentation

I do want to thank the hard work of the engineer that spent the time recording the videos over the weekend. Also, John P for posting my video.

Really, I wanted Alex Shiels to give the presentation and I hope he does at some point. My presentation was just an overview of User and Automated testing, so I hope that people either find the information they need themselves if they are interested or another presentation which drills down what is needed.

Possibly Related Posts:


WordPress 2.6 and Personal Projects

Posted by Jacob Santos on April 7, 2008 Comments Off

It is nice that WordPress 2.6 is not due until August. I was thinking that I would only have a single month for my pet projects, but I’ll have more than two and a half months to finish what I need. I believe with that amount of time, I can polish the patches I made in January and provide better arguments for inclusion into core.

Inline Documentation

Also, the biggest project will be finishing up the inline documentation for WordPress wp-includes folder and the wp-admin/includes folder. There might be functions in other places, as well as adding file level phpdoc documentation to files, but those won’t take very much time. Going forward, I believe it will make sense to document everything else that remains in 2.6, so that developers understand that each new function needs to be documented before it is committed.

Already several core commit team members are adding phpdoc inline documentation to new functions. However, not every core team member is doing so. I believe it will be easier for the community to provide patches for these mistakes, but not everyone is going to care and if care is not taken then a similar problem in earlier versions will appear in later versions.

I don’t want to see, two years from now, many functions which aren’t documented.

I’m thinking I can finish the inline documentation before June, but I would have to work every day, plus weekends to complete everything. It usually takes about 16 hours to document the bigger files, like functions.php, etc, and 8 hours for some of the smaller files. I’m not sure how much time I’ll devote or when I’ll start, but it is something that only has 20 more files to complete in the wp-includes folder, which is the most important to complete. So it would take around 10 days, if I worked 24 hours nonstop, which I’m not going to do. Well, I’m going to have to try for the second week of June for completion. For the wp-admin/includes folder, I’ll have to add another two or three weeks.

I probably won’t be finished with this project until July.

Writing Test Cases

This isn’t part of the WordPress repository, but it does go with it. I’ve stated before that my intentions were always to complete the inline documentation for WordPress and then move on to help write the test cases for WordPress.

The neat thing about writing test cases is that eventually, you’ll come across a bug and will have to write a patch for that bug, or at least seek out bugs that currently exist and write test cases which test whether or not that defect is accurate or not and provide a patch for it.

The goal of this mission, is to clear out most of the defects in Trac and try to make either WordPress 2.6 the most stable it can be, or at least WordPress 2.7 the most stable. It just depends on how long writing the inline documentation will take. Most likely, I’ll only have less than a month to start writing test cases and get patches in, which will put the WordPress 2.6 release somewhere in the beta and RC release stages. Not a good time to start, so at least WordPress 2.7 will get the most patches from the work.

The goal is to write as many test cases as needed for as many functions as possible and writing patches when needed.

Another possible goal is to write test cases for the enhancements, as to whether my patches actually succeed in adding the enhancement. The goal then, will be to get the Trac tickets to less than a hundred with it primarily consisting of enhancements and tasks. However, this is optimist, but really the community as a whole will provide the majority of patches.

The secondary goal is to reduce the overall amount of Trac tickets.

Google Summer of Code

You know, I would really like to be accepted into this program, but I’ll have to finish as many files with inline documentation before I start and it will probably throw off my above timeline. If I’m accepted, I’m going to spend the majority of my time working on whichever project I’m accepted for.

This really means that I’m probably only going to work on the phpdoc on the weekends, but for only a few hours, so it will slow down my timeline for inline documentation, but I still hope to have all of the files in wp-includes finished before WordPress 2.6 is completed. If I’m accepted it will also look like I won’t even get started with writing test cases until the Fall, which will give me a lot of time to devote to writing test cases for both WordPress 2.7 and up towards 2.8.

OTC Spring Semester 2009

If I’m graduating this Spring, then I’ll be going back to school next Spring to start my Internet Application Development degree. I do not plan to be active in the WordPress community at that point. I might come back to write test cases and inline documentation when needed, but if my above projects are completed, then I don’t think there will be a need me any longer.

Therefore, I’m thinking ahead to creating a photo gallery application or joining Zen Gallery project. I also look forward to fixing Mecha Asylum and rejoining the Asylum Futura project and releasing Mecha Asylum as a branch to that project. There are a couple of other game projects that I hope to work on during the school year (which really shouldn’t be difficult, since I’ll already have my core classes finished and would only need to complete the degree classes.

I’m probably looking at three semesters, depending on whether I go for full time or part time. However, I’ll be paying for everything, so I’m pretty sure I’ll only be taking a few classes at a time to not break the bank.

Regardless, I do think I’ll join the WordPress community again in the future, but it probably won’t be until I have gained progress on my other projects, like DragonU.net, AbsidonGames.com (which I want to be able to have repositories for, with Trac and eventually continuous integration), SantosJ.name (not just a blog anymore), and the browser game projects. Well, besides the browser game projects, which take about a three months to develop, the other projects could be worked on and completed throughout the 2008 year.

2008/2009 Plans for Sites

Mostly with DragonU.net and AbsidonGames.com, I want to switch them over to WordPress as the CMS and use it for the pages and designs. That way, I don’t have to write a custom administration panel for the sites and will have everything I need to allow other people to manage the site along side with me. I’ll also be able to write plugins for the rest of the authors and modify the themes. I’m probably going to use my current theme that I bought a few years ago for several months. After that, I’m going to buy a new theme or try to get a new custom theme for both sites.

AbsidonGames.com is a bigger project in that it will require adding Trac support and probably a plugin which allows for adding members of the blog to the Trac and Game Repository System. So everything will be managed by WordPress and who has access to what. It can be done in stages, which it probably will anyway, but I want all of the game sites on my hosting server to use Subversion and not FTP. However, to do so, I need to be able to allow new users to sign in and register automatically.

AbsidonGames.com will provide the news network, so that someone would only need to go to AbsidonGames.com to see what is being developed. Also, the games will grab the RSS feeds for their news section, completely replacing the need to have a news administration panel in the games. There will probably be one anyway, but probably not for adding news, but managing which feeds are added, as well as which news items are shown.

SantosJ.name just needs a photo gallery, my resume (probably just link to linkin along with a printable site version), as well as a picture of myself. I’ll probably also go through all of the articles I’ve written and either expand upon them to create something bigger or tag them. I’ll probably want to extend the Browser Game Development articles I started to write, since they get a lot of traffic.

I keep saying that I’m going to improve these sites, but never seem to get around to doing so. I think also for Absidon Games and DragonU, that the biggest time waster, was the custom CMS that I built. I think going to WordPress will save a lot of time and allow me to focus on just the content and additional features, instead of working from the ground up.

Possibly Related Posts:


Talk at WordCamp Dallas 2008

Posted by Jacob Santos on April 3, 2008 Comments Off

I think my session has more in common with Mike Naberezny’s talk at OSCON. The video will be coming out, but you’ll probably realize that Mike knows more than me on the subject. I am just guessing, but you can compare and contrast.

My focus was to get more people to build test cases for the Automattic WordPress Tests automated test suite, which focuses more on integration testing (what I commonly call functional testing, albeit inaccurately, but it is a habit).

I look forward to slides for Mike’s talk, which hopefully is released afterwards. I’ll like to be able to go next year, if another testing methodology presentation is given. I’ve been learning about automated testing for the past year and what the different methods can offer. I hope to graduate to understand what smoke tests and all of the other testing that Mozilla does. It would be interesting to apply those methods to other projects of mine and find out whether or not the quality improves.

My hope is that such a talk won’t be needed again next year, because WordPress would have finally grown up and completed several Quality Assurance projects. It would be nice to not have to read how poorly written the application I use is, because then I feel as if they are somehow implying that my code is also bad.

As an aside, when did Planet PHP syndicate, so many great blogs? Wow, just wow.

Possibly Related Posts:


Testing With WordPress Presentation

Posted by Jacob Santos on March 31, 2008 5 comments

My time was pretty much cut short before I was able to fully talk about all that I wanted to talk about, so I’ll apply more clarity to certain parts that may need it. To be honest, I didn’t think I would have enough material to cover the full hour, but from how it went it appears that I could have gone on for two hours and still not completely covered the full scope. I could have also done without the user testing and focused completely on the automated testing portions, since the majority of the people who weren’t developers left anyway.

I was probably better off having a smaller audience, because I wasn’t as nervous. I think I did well, once I talked past the introduction and became comfortable with speaking to the audience. I’m going to have to watch the video to make sure that is the case and I will update this post if there are any other parts I need to explain better.

The WPTests Tool

I think the first part is what my tool, WPTests is and what it does, and what it is meant to do. The WPTests tool is to check the status of the Automattic WordPress Tests without having to download Subversion, set up Subversion, set up the config, and fix other issues. I don’t include a readme or help, and I only fix one issue that I have.

My intention was to send Alex my patches for the Automattic WordPress Tests and then my issues would be fixed and so would others that use my system or just download that system. I also wanted a tool which would work on Windows and allow me to record the progress. I do need to optimize the SQL queries in order to increase the performance or at least create pages based on dates. This would allow for getting all of the test runs in a single day to be displayed and then have the last test run for that day for all of the other days.

The tool provides a history, to give context to what the failures mean. If all of a sudden the tests all fail, then you know you shouldn’t upgrade. The problem is that the test runs are only once a hour, two minutes past the hour, so an issue might be fixed within that time, but the person would have to wait an hour or slightly over an hour before they would be updated.

It would also be great to have historical data on what tests failed and when and when the test passed. I like the tool, but I have plans for another, which are more personalized for the user, which will allow for choosing which test to run, which plugins to run, different options that the Automattic WordPress Tests supports and finally see the results of that test run.

Both tools are based on the same code, so it isn’t difficult to maintain both and I do plan on maintaining both. The tool I presented at the session was mainly to prove to Nikolay of Automattic of my intentions and what I wanted, which is something akin to continuous integration, but not exactly.

The tool can be download at wordpress.svn.dragonu.net/WPTests and you will need Subversion to do so. I do not have tags, so you just check out the root and you are ready to go. I do still plan on giving this to Alex and hope that he accepts at least part of it in to the Automattic WordPress Tests.

My WPTests tool does not support PHP4, you must have PHP5.1+ and PDO_SQLITE extension enabled to run the tool. You can however change the DSN and since all of the SQL is supported by MySQL also, you shouldn’t have issues. What you will have issues with, if you switch over to MySQL is that I use the TEXT field type, so a lot of space will be taken up. I’ll change that later, so that both are supported at a later date.

Amount of Test Cases for a Function or Method

The one failed test case was not the only test case covering that method. If I did not have that test case, then I would not have been able to figure out that my method was not working correctly. For that method I had four test cases covering about 3 lines of code (I’m being serious). For the entire class, I had a total of 15 test cases covering 4 or 5 very small methods.

When you write test cases, you want to write at least one test for valid input and at least one test case for invalid input. For each branch (if statement, while loop, for loop, anything that might require brackets) needs to have at least one test devoted to just that.

So all of my test cases covered almost all of the possible cases that a user will be using my methods for. I also thought ahead and thought of twists to make sure that my assumptions weren’t wrong and then I’ll have issues down the road. The failed test case was an assumption I had that I was unsure about. I was providing support for PHP4 and I can’t exactly test with PHP4, because of the way I have the PHPUnit library set up and what extensions I require. In theory, it should have worked perfectly, however that was not the case.

It is perfectly okay to write just one test case per function, but do realize that with one test case for one function, it might give false impressions over the reliability of that function. A function having one test case is only useful if that function only has one line and is calling another function and that is all it does.

You also want to split assertions made in a test case into multiple test cases, if you have more than one assertion in a test case. The reason is that, once there is a failure of an assertion in a test case, no other assertions are tried in that test case. If you have 5 assertions in a single test case and the test case fails after the first one, then the other 4 will not be reported as failures or even show up in the total. If it makes sense, move the other 4 assertions to their own test cases. If the assertions are dependent on each other, then by all means include them in the same test case.

Skipped and Incomplete Tests

I had to skip over the explanation of both the skipped and incomplete tests and how to do that. There is an issue I have with the current Automattic WordPress Tests automated test suite, in which test cases exist for a nonexistent function. The solution to skip over that test is to set a constant to false. That is not the correct way to solve that problem, because I want to run the other known bugs and you should always run the known bugs no matter what.

The correct way it should have been done is to test for whether that function exists and if it doesn’t, then mark that test case as skipped.

Skipped tests aren’t so much a problem as failed tests and errors, because it just means that whatever the test cases was using is not supported and it can’t run without it. If that component is important, then it probably should bring down the entire test suite.

Incomplete tests are test cases, which the developer started, but did not yet finish. So you can use this to your advantage, you can design all of the test cases you want for a component, mark them as incomplete and then go through and finish them all later. I would just as rather not do that, because you shouldn’t have a lot of incomplete tests and mostly it doesn’t take long to look through a function and write test cases for that function or method.

What the Number of Failed Test Cases Means

I don’t think the explanation I gave matched what I wanted to say. If there is a failed test case, then you should assume that there is a problem. That is until you look at both the test case and the function or method it is testing. If you find that the problem is the test case, then the test case should be fixed. If you find that it is the function or method that is the problem, then it is a bug and needs to be filed. However, both the test case and what it tests should be looked at.

What I said, was basically, the formatting test suite covers a full range of test cases. Not all of those test cases are perfect. Some are feature requests, which haven’t been filed and probably won’t be fixed. Therefore, you can safely ignore those. There are also other problems, where the actual test case is wrong and needs to be fixed. There are or were other test cases which actually found bugs in formatting functions, but it has been a while, so I don’t know if they have actually be fixed or looked at.

It can also be assumed that unless the entire automated test suite is brought down in a fatal error, that you can successfully upgrade WordPress. It does mean that there will be issues with bugs or regressions, but those should be bought to the developers attention.

Names of the Methods Should Mean Something

I’m in the camp that method names should mean something for that test. Meaning I should be able to read the test case method name when it fails and get an overview of what happened before I actually look at the test case and function to see where the problem is. It is a convention and with any convention it is up to the developer. If you want to write the function name and just have test_function_name2() and test_function_nameN(), then by all means do so.

What is important is not the method name of the test case, but that the test case exists. I will not fault you for naming it how Alex does it in the Automattic WordPress Tests. Alex might even change my way of naming the test case method names to something he likes. I am not an elitist on the subject, even though I did slightly mock Alex during the Session, even if I didn’t purposely mean to. My purpose was only to question, which way you would do it and finally advocate mine.

You can name it any way which the test case name makes sense. Either way, I’ll be happy if you just do it.

A List of “Thank Yous”

  1. Charles Stricklin – I wanted to thank him for allowing me to speak at the Fisco, Dallas WordCamp 2008, even though pretty much no one there knew who I was and for giving a really geeky presentation.
  2. I want to thank Branson Tourism Center and Branson.com for sponsoring my trip down there. For my work to do that, is awesome. I don’t think some of the other places I’ve worked out at would had extended their hand (and wallets) in that way. Larry and Lianne are really great people to work for and I would say that, even if they fired me tomorrow and say that years after I do finally leave. Of all of the people I’ve worked for, there were very few who I actually appreciated working for and would do anything for. It isn’t just that they are nice, they are, but it is the respect and that is the most important when I work for a company.
  3. I would like to thank the city of Frisco, Texas for allowing WordCamp Dallas 2008 to be held there and appreciate the technician who ran the cameras to record all of the sessions. That was really great of the city to allow all of us to use their facility for the event. The city is just really beautiful.
  4. Everyone else who stayed for my session, thank you. I also thank all of the people who I talked to and told me about theirselves.

To Be Continued…

This post will be updated at a later time, when the video is available and I can go over more of what I missed and didn’t fully explain.

Possibly Related Posts:


Ideas for WordPress 2.6 and WordPress 2.7

Posted by Jacob Santos on February 7, 2008 3 comments

I have had several ideas to add to WordPress that I want to finish before I move completely to some other projects. I’m thinking if I get most of them done before 2.6 is started and 2.5 is out, they’ll be able to get in WordPress. That is a dream, and I don’t have commit access, so it is totally up to the commit team.

HTTP Request and Post API

My idea for HTTP Request and Post API is finalized, except that it has not been included into WordPress. I’m unsure why that is, since I have included, both documentation and unit tests that covers the full extent of the library. I also stripped out most of the extraneous material.

I’m about ready to do a complete and major overhaul of the system, once again and see about instead creating a set of functions which is pluggable, instead of classes, which do the job. It would be less flexible, but I think the change will be more the way that the devs would like it. It stands to be as long as wp_mail() however.

The last test I can do, is profiling the code, to make sure that it is quick enough now to work in WordPress. If I do that and I prove that it works and doesn’t create too much overhead, I’ll be seriously pissed if it doesn’t get in.

WordPress Logging API

I did some initial work on a WordPress Logging API which will capture all notices, warnings, and errors, and have them logged to an array for a plugin to later access and do what the plugin will with the array. This will first disable displaying of PHP errors and notices and will secondly, allow for better debugging, both on a live system and on a debug system.

The API is complete and I’m unlikely to do any major overhauls on the system. I think the next step is to focus on major areas that could use the API and convert them over to using the new API. I was hoping to get the API in 2.5, but I think major areas could also be switched over to using it.

I’m thinking I’ll focus more on getting the API in 2.6 and do a lot more work on converting major sections and other logging sections over to the system. I also will need to do profiling to make sure that calls don’t cause too much overhead.

Controller API

WordPress already has and uses the controller model, but it is not easy and is convoluted in many places. I would rather create a system which the WP_Query and Rewrite is combined in areas and allow for an easier model for adding pages. I would very much like this idea, but I don’t see myself creating it for 2.6 and I doubt it will make it in 2.7. I’m thinking that with the amount of time I can spend on it, it might see the light of day in WordPress 2.8, if the commit team is fine with replacing the rewrite and query model.

Single Use Form Nonce Tokens

The current nonce form token system is lacking in some areas and I would rather see some additions that allow for replacing CAPTCHAs, but are safe enough to be deployed in public systems. I would rather this also be in WordPress, so that each plugin doesn’t have to create their own system.

I have the code, however, it is not licensed for use in GPL, so I’m going to have to rewrite the code for WordPress. I am also going to have to write some unit tests also. It will require going to a session based setup instead of a cookie based one. I believe, my plans for having it cookie based also has it use sessions.

I should note that it isn’t completely secure, but it should halt most of the lesser intelligent bots. I person would be able to defeat the nonce easily, but would require a lot of work. Spammers would not be interested, hackers probably will be.

New Plugin Architecture

There has already been discussion on this and I think I’m over not being able to get it in 2.5. I think having it in 2.6 or 2.7 is fine and I’ll be willing to do work on it for 2.6 during any downtime. However, I do think that this is probably medium priority on my list. It would be fun to write, but I want to get some of the easier and more complete components finished first.

Possibly Related Posts:


WordPress Plugin Writing

Posted by Jacob Santos on January 7, 2008 5 comments

The WordPress Function Documentation blog has several posts about the current state of inline documentation.

However, I’m currently writing a daily series on Plugin authoring that will last until I either get bored of writing the series or I run out of ideas. The plan is to write as much as possible on plugin authoring and then eventually move the contents to the codex and to a WordPress Developer Manual.

So far, I’ve dived into the deep end of the WordPress Plugin API, but I’m eventually going to write posts on the add_filter() and friends functions on their usage. Eventually, I want to cover all I can on the Plugin API, which is my “field” that I’ve adopted in WordPress.

I will eventually move on to covering the other subjects, but it really just depends on time.

Each post that I’ve written does not exceed 500 words, which keeps the information concise and to the point. Eventually, I believe creating a larger document for other areas.

While the blog is primarily for function documentation and the progress of inline documentation in WordPress source. I do want to expand to user documentation fields and much like the posts for the Developer Manual, expand on user concepts in order to eventually create an User Manual.

The nice thing about the blog is that when I write a post, I sent the publish date to the next day of the last post. As long as I keep creating a post a day or several every other day, I should have a blog that has a post every day. Well, that will be tested as soon as I start school and WordPress goes into the forethought of my mind.

The goal is not to have a post a day, the goal is to write as much as possible about WordPress documentation to eventually create something bigger.

Please note, the contents of the blog are licensed under GPL v2, therefore all contents are with permission to be used under the restriction of that license. It is impossible to publish modifications back to my blog. I do think it would serve its purpose if you published modifications to the codex or if you so choose to do so at your blog and retain the GPL v2 license for that post.

Possibly Related Posts:


WordPress Documentation Informal and Unofficial Roadmap

Posted by Jacob Santos on December 31, 2007 3 comments

I would totally love it if WordPress had all of its functions documented. It could put WordPress with higher respect with developers. A lot is put on with the Codex, but the Codex is unstructured and doesn’t cover the complete depth of WordPress core and outer edges.

It is true that pieces can be picked up with the codex and trips to the code would allow others to pick up the rest. The WordPress API isn’t as difficult as some applications, so it has done without and flourished without a complete function documentation for a while.

That should change and is changing. However slow, it is quite boring to write documentation and depends on the mood. Realistically, it is very easy to get bored of it after working on it for a few days only to jump back on after taking a break of a few more days.

Documentation Process

For me, the way I’m now writing the documentation is by first going through and adding PHPdoc style documentation to all of the functions and then going back and adding @since information. Well the complete process is as follows.

  1. Add phpdoc style documentation going down the file to all functions and others that can be documented. Usually just a template which I copy and paste.
  2. Going back up I add the function name as well as @since
  3. Going back down I try to add short description information if I can, but definitely the parameters and return type information.
  4. Going back up I complete as much as possible the long description, but definitely the short description.
  5. The long description that is still needed, I usually ignore until it either comes to me or I want to finish the documentation for the file.

It might not seem like much, but on average documenting a function can take anywhere from 10 minutes to between 30 minutes and an hour and the more difficult and longer functions.

Old Style Documentation

There have been attempts to document the code before, but the extent is no where near the level of the documentation process. It is likely that because documentation does cause minor overhead to the PHP execution that a lot of documentation would slow WordPress down. However, that should not keep the documentation from the core.

If someone really cared about removing overhead from comments, then they’ll most likely do premature optimization and remove as much white space as possible also and combine as many files as possible. Premature, as the most overhead is likely with the database.

A few projects have noticed an increase and so have a build environment which has the comments, nice format, and split into multiple files and then through the build process compress and combine the files. If someone wanted to squeeze a few milliseconds, then be my guest.

The Roadmap

To me, it would be a pipe dream to think that all the functions in wp-includes would be documented before WordPress 2.4 comes out. However, I would very much like to complete the documentation in the folder before 2.5 comes out. In that way, the core development team can keep up with documentation themselves and the hardest part would be complete.

The team has started to make sure that any new function that goes in gets documentation, which should stop the flow of undocumented functions. However, it would be better if more people offered to help with the documentation. The standard is there and the support is there.

WordPress 2.4 is moving the business logic from the presentation layer in the admin panel backend. Therefore, those functions should also be documented. Hopefully, I hope to also have those done before 2.5 is out also, but going off what I have currently done and how much I have to go to complete wp-includes, I’ll be pushing for WordPress 2.6.

After the Function Documentation

I plan on focusing more on the unit testing and DocBook type documentation. It would be great to get WordPress to the level where has complete unit test coverage of the WordPress functions. Covering regressions, as well as bugs.

It would put WordPress on a higher level with developers, in my opinion, if I know that whatever code I applied went through unit tests to make sure it didn’t cause any regressions and actually fixed problems.

There is someone working on this and since it is supported by Automattic, should be continued without outside help. It would move the test coverage along if more people helped out, because user testing can only pick up so much.

The next step after the unit tests or automated tests, is acceptance testing. Which would automate portions of problems for users and test for common failures.

With an comprehensive WordPress User Guide and Developer Guide written in DocBook markup, it would allow easy access to common answers to users’ and developers’ questions. It would also remove the need to traverse the sometimes difficult to navigate codex. The guides would also be condense enough to provide pin point details instead of trying to describe everything as much as possible. With shorter amount of text, more people will be more willing to actually read through the sections to where they need to go.

WordPress Documentation Plans

The codex is not bad, but it can be improved for both developers and from the work on the user guide and developer guide, long portions should be moved back to the codex to allow for further modification and improvement.

The best thing about the DocBook User and Developer Guides is that they are completely translatable and multiple versions can be available on the same site for those native users. The User and Developer Guides would prevent translators from having to translate the huge amount of text in the codex to provide simple answers.

It is a hope, but there is only so much time. My attempt is basically to jump start the process, so that others that come after me won’t feel as overwhelmed as I do now. To my knowledge and to those that came before me, I believe they also shared my hope. It might have taken one or two years before I came along and put forth a small amount of effort. However, if I don’t get the documentation finished, I believe that some awesome person will come after me and finish what many others have already started.

Possibly Related Posts:


PEAR Channel for WordPress

Posted by santosj on October 1, 2007 Comments Off

After researching PEAR channels, I’ve come the conclusion that it should be placed in an installer framework.

I will still continue development of the other two in the framework and continue work on building a PEAR channel for WordPress, even if it would use my server instead of the official WordPress server.

I’m thinking it won’t be that difficult. There are some areas that I’m unsure of, but I should discover them when they come up.

Possibly Related Posts:


Web Application Installer/Upgrader

Posted by santosj on September 27, 2007 4 comments

I’ve been contemplating this problem. I think the system should support three methods rated based on the preferred methods.

  1. SVN (version control, preferred method)
  2. PEAR
  3. HTTP

I would prefer Subversion (VC)

This should be the preferred since the version control already has a system in place for downloading, updating (upgrading), and merging based on what changes someone has done. It would only need to get the URL to the subversion and have the location of the Subversion application or by checking if the Subversion extension for PHP is installed.

This wouldn’t require that the installer move the old files to another folder and can assume that subversion can clean up any changes. There might be problems when conflicts occur, but I think for the majority of people that would used this method wouldn’t have problems if they left their files alone.

I think this will be possible without too much trouble. First search for the SVN extension and use it, else search for the SVN application.

If neither exist, then go to the next method.

PEAR

PEAR is an awesome method of installing an application. If I can create a PEAR channel and use that to install WordPress, I can also use it to upgrade WordPress, when it needs to be. This could will need further checking. It needs access to PEAR, either the command line, or PHP extension.

This would most likely require moving any changed files over to a new folder and allow the person to copy over what they changed. I don’t know how PEAR handles these situations, but it is better to be safe than sorry in this type of situation.

If neither exists, then go to the next method.

HTTP

Not the best method as it would require moving existing files in the event that some might have been changed. The other problem is that like the above, it would require that the four methods work of GETting a file work. If any of them fail, then the installer would be broken and have no other fall back.

If None of them Works

However, I do think that for most people at least one of the methods above would work for most people. Those that it doesn’t work for, would have to use the age old FTP method or try to find someone that will do it for them.

It has to just work

This means that for most people it has to just go out there and try to find the most common places where Subversion and PEAR exist, if they are installed. It should also try to use multiple methods of getting a file by URL. It should allow for configuring the locations and methods used instead. An “auto” method for novices or people who just want it to work and a “manual” method for more experienced users or for people who want more control.

If it works out, I will apply it to installing Astrum Futura.

Possibly Related Posts:


WordPress 2.3 Upgrade Planning

Posted by santosj on September 10, 2007 1 comments

The upcoming release is coming out and I am looking forward to upgrading. I think I will spend a little bit more time on older posts and clean them up a bit. I plan on organizing my categories and adding tags to older posts.

I think I should go back and add research to a lot of previous posts and take the time to look up where I got most of my information. Since a lot of it might be in books, that might be a little bit more work. I’ll see if any supporting evidence can be found online and then use the books as a backup. It would look better to apply some external resources for future visitors that might find the information. I don’t want them to think I’m talking out of my ass, unless I am and then I can just correct my mistake and move on. No one will be the wiser, except for me and the person who might come across the corrected post.

It should be fun, to look at all of what I wrote and fix grammar mistakes and add clarity where it needs it. It will be slightly depressing to see where all of my failed attempts are archived in plain view. Good times and I hope to eventually get back to those past projects: Heat of the Race and Mecha Asylum. I would like to do HEAT. It would be a really awesome project. However, I want it to be awesome and I’m reaching up to the point where it will be at that point when I start coding it.

First things first, I will have to do a backup. WordPress 2.3 has a few major changes that could screw up and blow all the hard work away. After that, I can get started on the above.

Possibly Related Posts: