Jacob Santos

I released version 0.1 of the PHP web application versioning web application. The first release is rough around the edges and needs to be modified in a few places. I do think it has always been a good start and also has been very useful for what I needed it to do. However, as I move forward I want to position it for other projects besides WordPress and it needs to be polished. Also, since it is open to the world, it needs some better quality controls attached to it, so I don’t cringe whenever my name is associated with it.

What it is Lacking?

It is lacking inline documentation, test cases, solid installation script, decoupling of WordPress, support for more than uploading zip files, and a bunch of other requests. I’m going to work on the quality assurance parts first while decoupling support for WordPress.

The issue currently is that I really only support SQLite, but I’m going to finish support for MySQL also. This should hopefully ease up on the time it takes to search and load the pages.

Version 0.2 Features

I think these central features need to be addressed for the version 0.2 tag and release.

Purpose

The web application versioning purpose is to record the various elements in PHP that can be documented. Mainly functions, classes, class attributes, methods, constants, and limited global variable support (must be declared in a function as global). For web applications that neglect @since tag information, this web application will be helpful in finding that information. Since it was built for WordPress, it also supports filter and action API version information.

In WordPress 2.7, you will be able to update themes from in WordPress, as well as plugins. This is going to complicate those who have made modifications to the theme. Any modifications, currently, are going to be overwritten. That is to say that changes may be made in the future that will allow you to keep those changes. My point is only that if you are going to be modifying a theme, you should create a child theme instead and create the change there.

All you need is the style.css with the Template: Parent-Theme-Name at the top in the CSS comment. You then can create files with the same name as the parent theme. Some custom files created for inclusion will not work this way, unless the parent theme specifically coded to work with child themes as well. Regardless, you can copy over from the parent theme and create the changes there. If you are only changes a file or two, then it will work out great.

You will be able to upgrade the parent theme, gain the fixes and changes there and still contain your changes. Eventually, the DIFF support will find its way into the upgrade process of themes, but I still think the heavy lifting would be better placed on child themes than depending on the diff support.

I’m giving this inline documentation project one more week, before I set it on hiatus for a month. I still want to get as much completed before 2.7 is released. I just think that giving the rest of this week should be enough to at least finish the wp-includes directory files. I probably won’t get to the rest of the wp-admin files that have functions. I definitely not going to be able to finish up the wp-admin/includes files with inline documentation.

I’ll be lucky to complete the rest of the files in wp-includes. What I’m doing now is complete the files I know no one else is going to want to complete and then leave the rest to those who want to complete them. There are a couple I think that might be willing to do so.

Next week, I plan on working on plugins and finally complete a few projects that have been on my mind. It will be nice to have those out of my mind as I enter into my year long project.

Well, it might be motivation for the rest of the WordPress community to finish it. I think after working a month on plugins and getting the year long project started, I’ll be fresh to complete the rest of the inline documentation that remains.

It is hard to believe that, after an entire year of starting the inline documentation, with merely two files fully documented or 12% (Ohloh.net), that it is now at 27.7% (Ohloh.net). Well, it is more than that. With the entire WordPress codebase documented, that number should be well within or more than 30%.

It will also mean that WordPress will be at the level of Habari when it comes to inline documentation and beyond Habari when it comes to codex documentation. Well, I could have just worked with Habari and saved myself the trouble and time, but it was worth it. Or at least that is what I tell myself in order to sleep at night.

I think that I’m lucky that those before me put forth the effort to write inline documentation and I hope that those after me continue the effort. Just because a function has inline documentation doesn’t mean that it is complete. Inline documentation, just like the codex documentation has to be maintained. The nice part, is that the maintenance is at the micro level, meaning that when a function changes, only that documentation needs to change also.

One of my fears, is that people will forget that inline documentation needs to be maintained and it will become worthless because of it. My second fear that new functions won’t be documented has been proven to be unfounded. New functions are being documented by most of the core team and it seems that it matters to most of them.

Well, if I had a choice, I would choose incorrect inline documentation, because then it is easier to correct the parts that are wrong. Trying to add new inline documentation is not a task I want to take up again.

Only 9 files remain and after tonight, there should only be 8. After tomorrow, there should only be 7. After that, I’ll work on capabilities.php, comment.php, and widgets.php, which are the more difficult files to document. That will leave category-template.php, link-template.php, post-template.php, and theme.php. I think that with the rest of the week, it isn’t going to be exactly easy completing the *-template.php files.

I’ll be able to complete the functions that have short bodies, but that is only if I can complete the other files before the weekend. I can probably complete a file a day, there is no way I’m going to be able to complete all of the files left. The only good news is that comment.php is halfway complete anyway.

I seriously starting to think that if I actually thought I could get away with murder, I would have laid down several persons long ago. The only force stopping me is my lack of intelligence to commit the deed and get away with it and my lack of skill at hurting anyone. I suppose both are pretty big, but I think if I had the intelligence and the skill that when the opportunity presented itself, I would have jumped on it.

I guess I more frighten by the point that I feel nothing about my lack of concern that I think the way I do. It wasn’t until recently that not many people think about hurting others, even abstractly and metaphorically. The people I think about hurting aren’t real, they are abstractions of actions I would like to take, if given the chance.

In the realms of fantasy, there are no police and no consequences. Therefore I’m given free reign to do whatever with no repercussions. In the real world, the police ask questions and I’m pretty sure that they’ll see through my lies fairly easily.

There are too many unknowns and unpredictable unplanned occurrences that can happen during the deed. The safest course of action is to do nothing. Acting in a fit of rage leaves you open to mistakes made easily in the heat of the moment. It is best to wait until calm, but then consequences start entering the equation.

The question you must be able to answer, “If I am caught, would it be worth it?” The answer has currently always been negative.

The problem with killing people you know, so that you’ll be on the short list of suspects that the police will question first. If you actually did do it, then you would have to maintain your composure to ensure that the lie is believed. The problem then is also the alibi and seems to be the hardest to deceive.

It is unwise to leave it to someone else to lie for you, because if they are found out, then everything is ruin. Then again, coming up with a plan that involves the person not knowing they are telling a lie for you is even more difficult. What works (or in most cases doesn’t work) for the movies, doesn’t work for real life. Screw-ups are common for screw-ups and relying on average to below average intelligence to get past mistakes is not reliable.

Killing someone you don’t know solves that problem, since well, you’re not going to be on the list of suspects unless someone sees you. If there are no witnesses, then it will be difficult for the police to pinpoint you as the suspect. The problem with this is the motivations to kill someone you don’t know. If you don’t know this person, then there is no reason to murder them. To kill for the sake of killing doesn’t make sense either.

If you can’t kill someone you know and don’t want to kill someone you don’t, then I guess the only alternative is someone who doesn’t exist and in the realm where you can’t be caught. Well, unless you want to be caught, but there wouldn’t be any consequences in that, since the fantasy would end.

Hmm, I suppose it is good that I’m rational enough to realize that I’m not smart enough to kill anyone, because then I’ll be screwed. I have too much to live for, too much to accomplish, and too much that I haven’t yet done to be put away for the rest of my life. It is too much of a risk and I don’t wish to spend 25 years of my life based on a idiotic whim or spur of the moment. Twenty-five years is far too long to sit around in regret and being ass raped. I’ll rather not be ass raped, if it can at all be helped.

Actually, not being ass raped motivates me to against doing a lot of things. I ask myself, “Will my ass be raped if I’m caught for doing this?” If the answer is, “Yes,” then I don’t do it.

Inline Documentation

I have switched my focus to the wp-includes directory files, because there is a lot more support for documenting those files. Peter Westwood helped document general-template.php and Scott H helped with formatting.php. There are only 13 remaining files that need to be documented and I plan on finishing the remaining ones before next week is over.

I hope that those who have contributed will contribute some more. It is a great feeling to be down to such a small number, as opposed to the 26 files from several months ago. It is nice and I hope to have a few more files done today.

It is beginning to get to the point where the functions I’m trying to document aren’t within my ability to correctly do so. I’ll try my best, but I’ll hate to leave the functions without any type of documentation. If it comes to it, I might have to use the functions to understand what they are supposed to be used for. Doing so would take a lot more time, so I hope there aren’t a lot of functions that need this method.

Plugins

I still want to develop several plugins from my previous list. It would be nice to grow my list of plugins. There are some enhancements I’ve been waiting to do for a couple of my plugins. Alternative Mailer needs to support attachments, but I’m actually unsure how to go about doing that. It needs other enhancements.

WordPress Acceptance Tests

Finally, if I can get to it this month, I want to start writing some acceptance test cases using Selenium. WordPress 2.7 is a little too buggy for my tastes and I want to offer better QA, so that users won’t take up arms for the lack of proper testing.

It should go fairly quickly. I’m going to focus on the Administration Panels first and go through each page. There should be upwards to about a 1000 total tests. I think I’m also going to plan it out a bit more, so that it can be known when all of the tests are complete.

Given how much time I’ll need to devote to my plugins, I’m not sure I’ll be able to finish this month. However, starting it and then finishing it in October might give better reason to releasing WordPress 2.7 in November instead of a month early. Well, depends on I think it will take a full week to do everything I need to finish up the plugins and create the new ones. That will give me a week to finish this project.

Given my future plans I’m not sure I’ll be available to create any patches for the administration. It isn’t my area that I usually write patches for. Also, I’ll be moving on to other projects that use the WordPress library, but I don’t really want to support the Administration, unless I have to. Regardless, the tests and bug reports should help the community and core team fix the bugs on their own.

I’m not going to use the Automattic WordPress Tests repository. I’m going to create my own for this project. It is going to require more work than the WordPress Tests, so I’m unsure how many will actually participate with using it.

I’m not quite sure when I was dropped from Planet PHP. I haven’t been there in a long time and certainly haven’t posted on there for a long time, so it is no surprise. I think it is nice actually. I said what I wanted to say and I don’t think I have anything else to say about PHP, well at least not for a while.

The reason I joined in the first place was that there weren’t that many posts that I wanted to read. Now, there are more than enough posts that I want to read and also need to read. Many and better bloggers on PHP have joined the Planet PHP site, so I am not needed. It was fun and I’m glad they allowed me to join the community, but I’m happy being pushed aside and replaced by far better people.

I started visiting the site again and well, I enjoy it once more. I’m visiting the site more and more, so my addiction to PHP news is coming back. It is a safe drug I can get used to. I’m still addicted to WordPress news, but a little bit of PHP here and there couldn’t hurt.

I plan on retiring the Planet PHP category and moving the posts over to the “PHP” tag.

There are reports of a few people who are running the latest trunk of WordPress on a live blog and that is a really bad idea. The merge of Crazyhorse is still being stabilized and there are quite a few areas that I’ve tested, on a dev site, that are currently broken.

I believe that the level of stability of the Crazyhorse merge is increasing and I expect I’ll be able to SVN Up to the latest revision. I’ve been keeping a watch on the trouble areas, but haven’t been reporting issues until it is stable.

I think one of the issues is that the new “Inbox” includes test data, that I really don’t want to have on my blog. Yeah, I can delete it, but I don’t know what it is for currently, and I don’t want test data on my live blog. Hopefully, for those who have updated, it will be removed, but I suspect that including that in the upgrade process might not make much sense.

That said, from what I’ve seen, it is looking better. I’m impressed with the features and increased usability of the new version. When everything works and it should before WordPress 2.7 is released, I think many people will be happy. If not a little bit upset with yet another major interface change, since WordPress 2.5. People will eventually find that the new interface is a lot easier and better.

You can already change the Administration Panels, if you don’t like the changes.

Who am I to suggest this? Well, you can do what you want. Just be sure you don’t get mad when it hits the fan and I strongly suggest you test WordPress locally. When I say, “Test” I don’t mean you just write a single post and see if that works. I mean you go through every page, hit every button, input every field (that you want to know working), everything! to see that it works. If it does, then let me know.

A lot of inline documentation has gone into WordPress 2.7 today. The file script-loader.php has been completed and is one of the more easy files to complete. The file formatting.php is also completed, but is awaiting commit to the WordPress Trunk. Thanks to Scott Houston for helping with the formatting.php file, documenting over 90% of the file.

Now that post.php, functions.php, and now formatting.php are finished, that remains are only 14 files. There are 5 files that deal with “template tags” that have mostly short function bodies that will really easy and quick to document. There are still three “easy” files that need to be documented. There are at least two files that I’m not even going to touch until the end.

I hope to complete more of the template files, so that theme developers can reference that documentation. Hopefully, the idea for adding phpDocumentor or PHPXref site to wordpress.org subdomain will go through before WordPress 2.7 is out, so that people can reference it. It would be better to reference a wordpress.org site for on the Codex and other sites, because you can be sure that it will be up.

It looks like my personal goal of having the inline documentation finished might just come to pass. There should be enough time to complete the inline documentation by October / November release date (historically, WordPress developers try to release a month early).

Heat of the Race is a racing simulation, that is text based. The player customizes their cars and bikes and competes against other players. The setting will take place in the future, so that the car and bike components and racing locations will be futuristic.

The player will win money from races and will be able to buy better parts to go faster, and complete races better. There will be racing teams that will help each other and will be able to compete against other teams to win greater amounts of money.

Cars / Bikes

The cars and bikes will have attributes that each part will increase or decrease depending on the quality. The speed of the car won’t matter much, if the vehicle can’t turn at the top speeds. The amount of upgradable parts will be small with the first version, but the amount will increase as development continues.

There are two types of bikes and cars, one will be with wheels and one will be hover crafts. The player can have both types, and unless they have both they will be restricted on which race track they can go on.

Some attributes don’t really make sense, since the player will not be able to control the car and will get the results quickly. It is text based, so there isn’t much that can be done to allow the player to control the vehicle. Future versions might have something from old Nintendo and arcade games to improve the racing experience. The first version will just give the results immediately.

Race Tracks

There will be several race tracks with different qualities of turns, wetness, temperature, etc that will affect the cars. The race tracks will also be one different planets and in outer space. There will be attributes for the race tracks and will also have grid layouts. This will allow for calculating the car attributes based on each race track, like it would if they were playing an actual PC racing game.

Parts

The cars and bikes will have upgradable parts, which will allow for improving the vehicle against other players. The full list has not been decided and will be developed after the game code is completed. The parts will be entered dynamically, so that new parts can be added quickly and current parts can be modified easily.

Teams

There will be the team leader that will control how much the fee to join and stay in the group is. The fee is optional, depending on the team leader and the team leader can use it for gifting players parts and setting as a betting pool for racing against other teams.

I want to develop the team mode to have many enhanced features for controlling the team almost to the macro-management level. I want to allow the team leader to do many tasks for the group, but have most of them to be optional.

This will most likely be a module, so that it can be applied to other games easily and quickly.

Conclusion

This game will be developed next year, during the first or second half, depending on the number of projects that have been completed at that time. Battle Machines will be developed before this, and this game will also be developed after Earth 3045.

I think I might create a simple version, much like the Farmer Sim pbbg, and then continue to add features after the games are finished. I think the goal will be to release very simple game which have all of the features. This will allow the games to be playable, but not take more than a month or two to complete and build off of the other games that came before it. Therefore teams might not be part of the first version.

The current game is a little convoluted and broken, which means it is unplayable until I rewrite it. I’m going to focus on a minimal feature set for the next version to get the game playable and improve the quality of the features. By keeping a small feature set, I can know ahead what features I should complete and how long each feature will take. Also I’ll know when I’m finished with the project.

This time I’m not going to open the game until I’m completely finished and the game works after testing and acceptance test cases are completed. In order to improve the quality, a lot more testing is going to be done for this game and all of the games I make in the future. It will take longer, but focusing on improving the quality before players bring it up should improve the reputation of the games.

Story

The main setting and story line will change. The game will take place on an alien planet, the soldiers from different fractions crash landed and need to rebuild their fleet to get home. The other fractions aren’t going to make it easy for the others. The players will need to regroup, rebuild, and fight off the enemy to escape the planet and head back home.

Focus Points

The focus points will be territory, soldiers, research, and buildings. These will be tied together and balanced, so that the meek aren’t completely overrun by the strong. There will also be time limits and the success condition will happen over several months.

I want the game to last long enough to where new players that joined late can learn the game, group with people and appreciate the game long enough to where when the next game comes along they can just jump in and start as soon as possible. They might not win, but they’ll have the opportunity soon. I also don’t want the game to be over soon enough to where none of the players had enough time to accomplish the objectives and enjoy the game.

Territory

Research items used to escape the planet will appear at different locations. Only when the fraction has captured the research item can the item eventually be used to escape. This will mean that a grid based system will need to be used in order to coordinate where the research items and what land the fractions hold.

The Grid structure of the game will limit the amount of land the players will be able to fight over and hopefully should limit the amount of players are in the game. I believe I’m going to have a main grid that covers the planet, sort of like latitude and longitude. Then sub grid coordinates with those and so on. The containers will be big enough to hold the player and a number of buildings.

This will mean that one piece of land is actually an square acre or larger depending on the amount of buildings I finally allow. Actually, I think I’m going to do it in sq. miles and sq. kilometers.

This should allow for quick access to where players are currently and I won’t actually have to populate the entire planet with coordinates. By calculating the distance, I can figure out how long it will take for one player to attack another. At the most, since the database table could grow to be very large, or at least the coordinate table with many rows. It won’t take that much space since the most the table will have is numeric values with one of those pointing to the player which holds that piece of territory.

There will also be mining to harvest precious materials in order to pay for mecha suits, buildings, and research. The amount of mines will only be preset for the initial land of each player. Captured land will be randomly generated and will remain until the game cycle is complete.

When the land is destroyed only the buildings on that land will be destroyed or captured.

Soldiers

The mecha suits from the previous game will be used in this game as well. The mecha suits will gain attributes that will be able to be extended, so that balancing can happen quickly. Since there are only going to be five mecha types, the base attributes might be hard coded with the modifiers held in the database.

The mecha suits will be built from buildings, and require men that will also grow depending on the amount of food, research, and housing. Housing is another type of building that can be constructed.

The different suits have different capabilities that allow for different maneuvering, strengths and weaknesses. Some of the land types will not be able to bring down the flying types, no land to air missiles. The strength and weakness ratio will be dealt with the Rock-Paper-Scissors usage. This will improve the balance and prevent one player from building one type to rule all. That said, there is still one type that is all powerful, but will be extremely expensive.

The attributes will be about four or five to start out, but I can envision that future versions having more. The difficulty is that the more attributes the harder it is to balance the game. I don’t think more than 10 will ever be used, but that will decide upon later and depending on the game play.

There will also be a mechanical device that will spy, thief, and capture land/buildings. This device, called a probe, will not have any attack capabilities, but will have other purpose during the game to help find the main research items.

A transporter aircraft will be used for land based mecha suits, this will be automatic and can not be built or researched.

Research

Research will be very important and I will build a tree much like the grid idea. The Research will have dependencies, amount of time to complete, and materials. I’ll create the tree after the component is completed and think of what will go into the tree after it is complete.

The feature seems to be easy to create, but it will be difficult and time consuming thinking of all of the research items.

Buildings

There will be different types of buildings for different purposes. The list below has them all:

There will not be much macro-managing with the buildings, so besides the research buildings, there won’t be many buildings to develop items. I could create buildings for developing weapons and armor, but I think that should be automatic and improved by researching.

Some of the buildings will have research and other building dependencies before they can developed. So for example, Advanced Armor Manufacture building, might require Advanced Armor Research II and Basic Armor Manufacture building. In this example, doing so will allow for the player to research Advanced Armor Research III.

In this way, the buildings will use the Research Tree module and just pull out a type to create the distinction between buildings and research fields.

New Player Protection

The game will employ “New Player Protection” to keep stronger players from attacking new players. This will be based on the strength of the player and as long as the player doesn’t attack anyone else. This should allow for new players to grow and learn the game without being harassed by other stronger players.

When the player has graduated from this status, there will be ranges for attacking. This is only in the event that the game reaches enough players that each range has enough players within it. I’m going to try to develop the ranges to where it is dynamic and allows for recalculating the ranges based on growth and the amount of players.

Game Cycles

The game cycles will continue until all of the research items are collected and a single fraction has collected all of the pieces needed. The research items will not exist all at the start of the game. I want to allow the game to continue for at least two or three months before all of the needed items are available.

There will be more than one research item available of the most basic items, which will be available at the start of the game. Other ones will become increasingly rare as the game goes on. The first couple of cycles will probably require that the research items be “dropped” near the territories of the players, so that they can be found within the five or six month hard limit, where the game will automatically recycle whether or not anyone “won.”

Collecting all of the research items is the win condition and required of the players to track the components down. This will force players to try to collect as much territory as possible.

Possible Modules

Modules are game components, which can hopefully be used on other games. If developed correctly, these modules below can be used in future and past projects. They will be developed separated and updated on all of the games, since they aren’t tied to any single game code.

The games will be developed around modular components to reuse as much code as possible. Each game will have separate components that won’t or can’t be used elsewhere, but as much code as possible will be transferred to the Quantum Game Library as possible.

There will be the code that will exist in QGL and the plugin code for the game engine that will use the QGL code. The code that isn’t dependent on a database will be committed to QGL and the code that does rely on the database will not be part of the QGL.

Conclusion

Well, the game won’t be that easy to create, but it will be more simple than the previous version, which had cities and population and based income from that. I like this design document better in the sense that everything ties together in a clear fashion and the code won’t be overly difficult with AI requirements.

Actually, there won’t be any AI requirements, which automatically make the game very simple to create. I hope to have this game out in production after two months of development. After the Farm Sim is complete, Mecha Asylum will be in production.