James Pic wrote a little article on how you can import the eZ Components SVN into your local GIT installation. This way you can stick to your favorite version controll system and don't need to use SVN much if you want to try out the latest features in eZ Components and use GIT as your favorite version conroll system.

I recently migrated my server to a new maschine and a new provider. After supporting Kore today with installing spamdyke on his maschine, too, I seized the chance to update my Spam Filtering with Spamdyke in front of Qmail howto on the wiki. The howto describes how to install the most recent version of spamdyke on a Gentoo system, explains the most important configuration options and gives some practical hints for such setups. You can ask Kore, it only takes about 10 minutes to do so ;) and saves you a huge lot of spam. Comments and addtions are very welcome.

After my server was close to wasting all its CPU time for checking email messages for potential spam using Spamassassin I decided that it was time to investigate. My friend Arne, who helped me a lot with Qmail problems earlier, recommended to install spamdyk, an SMTP spam filter that is placed in front of Qmail and does not require specially patches for the MTA itself. Spamdyk can filter mail by blacklisting, whitelisting, greylisting and using several other options.

Thanks to Arne for this great tip! Spamdyk is up and running now on my maschine and my load is now constantly below 0.40, while spam receival seems to be reduced drastically. Since I did not find much information about Spamdyk on Gentoo, I wrote down my experiences as a little howto in the Gentoo wiki. Maybe someone finds it helpfull. Any feedback welcome!

Almost 1 year ago I blogged about Ohloh, and eZ Components being registered there. Those days I just found it funny to see how they measure the project cost of open source projects based on the ammount of code contained and things. Recently I am actively watching Ohloh and I think, by now it becomes a serious project with real value for every involved party. The maintainers added many new features to Ohloh, since I last blogged about it, and many contributors started participating in the service. So, I want to revise my "review" of Ohloh from the last year and explain how I see it by now.

If you are familiar with Ohloh, you can skip the next section and just start with the "Where is my value?" part, if you like.

Ohlo features

Ohloh still measures open source projects and still has a cost and effort estimation for each project. Additionally, stats on documentation and size, respectively activity, of the involved development team are automatically measured from the projects source code repositories. Based on these statistics and statistics of similar projects, e.g. those which are using the same platform or programming language, Ohloh tries to automatically assign rating statements, so called factoids, to the project. For example eZ Components is rated as being "Mostly written in PHP", "Large, active development team" and "Extremely well-commented source code".

While I can confirm all of this statements and the first rating is quite obvious, the rating basis of the latter 2 factoids is not that clear at a first glance. But quoting the Ohloh website should give you a hint, how Ohloh legetimates these statements: "Over the past twelve months, 12 developers contributed new code to eZ Components. This is a relatively large team, putting this project among the top 10% of all project teams on Ohloh." and "Across all PHP projects on Ohloh, 10% of all source code lines are comments. For eZ Components, this figure is 33%. This very impressive number of comments puts eZ Components among the best 10% of all PHP projects on Ohloh. A high number of comments might indicate that the code is well-documented and organized, and could be a sign of a helpful and disciplined development team.".

In addition to the automatically calculated project stats and ratings, registered users can now write reviews about projects, give ratings about them and assign tags. It is also possible to register links, that provide additional information about the project, to add further source code repositories and to get RSS feeds about the project aggregated. While these are the usual Web 2.0 features, which you just expect in any upcoming web project nowerdays, there are some specialities, which I consider really useful and unique (mostly because the project is unique :).

As a user you can create a stack of open source projects you are actively using. Based on this, Ohloh tries to recommend projects you might also be interessted in, and presents users to you, which own similar stacks. While this seems just again to be the typical social aspect of Web 2.0 applications (quite senseless in itself, but fun to use), there are some really useful aspects here. I'll come back to this later. In addition, you get the chance to assign yourself as a contributor to a project and map the username you are using in the source code repository to your Ohloh user. This way, all your contributions to open source projects in are aggregated in a single place. Ohloh does not only provide information about your commit stats and your activity on the project, but also estimates your experience level with certain technologies, based on your commits.

Another important social feature is that you can give kudos to contributors for their contributions to a specific project. While kudos always existed in the open source world, this is the first time (AFAIK) that you can officially state your appreciation for the work of a contributor. Ohloh uses a quite complex algorithm to measure the kudo level of a contributor, which implies the kudo level of the user giving the kudo, the ammount of kudos he gave to people overall and also the ammount of users that stacked your project and some more.

You can enhance your own profile, by adding location information to it, so that users near to you will be shown in a Google map and users / contributors of a project, who are located near to you, are shown, too. The latest feature is, that you may add further information about the projects you contribute to, like the position you had/have in the project, the tools you gathered experience with during your work and the languages you used, which might possibly not be visible in the commit stats.

There are still lots of more features I could list here, but I'll leave this to your own experience with Ohloh. My main intention was just to give you a short overview, what the tool is capable to do. I guess that worked?

Where is my value?

So, this is just the usual Web 2.0 hype thingie, you propably think by now. There is nothing really usefull there, at least nothing which is more useful than, for example, Flickr. No, I think there is a difference here. The Ohloh project can become (and is already in some ways) a really sensible tool for different groups of people.

First of all, it is extremly valueable for users which are new to open source. Try to imagine that you are searching for a tool, which performs a specific task. Most propably you will be stunned by the variaty of projects that can perform the task or are related to it. In this case, Ohloh can give you a nice overview about the different projects and their activity state, which helps you to not get trapped by unmaintained or crappy projects. Additionally, you can get to know interessting new projects, by the recommendations of Ohlohs stacks and possible get in touch with other open source users and developers near you.

I expect you are not that new to open source, so this might propably not be a good reason for you. Additionally, there are different other websites, where new users can collect all those information, so it is not really a unique value, but only a nice enhancement to get the information in a single place. So let's look at another group of potential users, that Ohloh offers value for: Management people. Let's try the thought experiment again. Imagine you are an IT manager or software architect of a company, no matter if a small, medium or large size one. You now need to decide for a new tool to be introduced in your company for a specific purpose. What will your decision be based on?

Sure, commercial vendors will bomb you with marketing arguments, but you still need to research if there is enough truth behind those and it is often difficult to get some hard facts about the product you might choose. With open source projects you have at least the possibility to dig into the source code yourself (or possibly delegate this task to some developer). You can try to examine the code quality and dig into mailinglist archives to collect other users impressions. You can also try to estimate the size and skills of the development team. But all of this consumes a lot of time and if you need to decide among several projects, the task is almost impossible to solve. Ohloh solves at least some parts for you here and provides a well-thought basis for you, with many important facts in 1 central place. Beside that, you can directly see, if a contributor is possibly located near to you, which is propably interessted in providing commercial support and consulting for the project to you. You will also get an impression of the key contributors and can estimate the skills of a possible consultant.

Ok, let's finally stop with though experiments. I asume you are an open source developer. So, what the heck is the sense behind Ohloh for you? I mean, except the kudo thingy, which can propably boost your ego? At first, you get the chance to have all your project contributions aggregated in a central place. This is nice to look at. But beside that, it can also give potential employers a nice overview of your skills and engagements. Not only about your experience level with certain programming languages, environments and tools, but also about your way of working in respect to documentation and continuity and about experiences with tools. Furthermore you will receive feedback from your users and possibly an overview about other projects, your users make use of, for possible interaction or integration with these.

Good, I hope you identified with at least 1 of the above described people? You did not? Hmmm... then at least Ohloh can give you a nice impression about how much worth open source already is and a cool example how a cool Web 2.0 application looks like. ;)

^{I would appreciate if you try out Ohloh and possibly give me some hints on how you see things, here on my blog. Thanks in advance!}

Are you new to open source? Or if not, do you still remember, what it was like, as you first started with open source? I recently tried to remember these days... back in 2001, when I started playing around with PEAR and shortly after that started to work on my own packages for PEAR...

I'm quite sure, I violated at least 9 of the 10 rules I will try to write down here, which you should know about and which you should take to the heart, if you want to be a part of the open source community. At least, you should keep these rules in mind, if you want to join the PHP community, but I am quite sure, it applies to any other community out there, too.

If you want to start with open source development right now, be sure to read through the following rules, before you act any further! I'm sure, you have lots and lots of great ideas in mind and can not wait to talk them out loud and start realizing them. But, take a deep breath first and read the following rules, think about them, take them to your heart and then start over and rethink them again...

1. Stick to your level of Karma

Open source is not a democracy. You have heard something different? This is wrong. Always keep in mind: Open source is not a democracy. Every developer has a certain (unexpressed and unexpressable) level of Karma, which allows him to decide (or even dictate) things and to make use of certain infrastructures of the community (like their version control system, their servers,...). Think of Karma like your points level in a role playing game. The more levels you played and the more riddles you solved, the higher your Karma level grows. But beware, it may also drop, if you act unproperly.

That said, if you are new to a community, your Karma level is 0, per default. You should always keep that in mind. So, what is this all about Karma and stuff? Karma basically means the trust the community has in you. It is not possible to measure Karma in a number or even to guess it, because there are so many factors influencing your Karma and your Karma level is different for every individual of the community. For example your level of technical experience usually highly influences your Karma: The more you know about the subject your project is about and about the technical environment, the higher your Karma will grow. Another factor is the amount of work you spent for the project: If you're a member of the project for ages and spent thousands of hours of work during that time, your Karma will propably be high, too.

There are many more factors, which influence the Karma of an open source developer, as you will experience in the following weeks and months. What you basically should remember is: If you are new to the community your Karma level is (at least near to) 0. To raise your Karma you need to show the community that you are trustworthy. Do so by simply sticking to the following 9 rules.

2. Information is Karma

The first thing you might propably want to do is asking a question or proposing a cool idea to the community. Most propably, you will do so on a mailinglist, which is the most common communication channel in the open source world. Keep your self back from that at first! People get annoyed really fast, if you ask something which is obvious in there eyes or if you propose and idea / ask a question, which has been proposed / asked by others before (especially if this already happened multiple times).

So, what should you actually do before posting a question? Search for information! Try Google, the projects website, the mailinglist archives, the projects blog planet and any resource you could ever imagine. Don't perform just 1 search, but refine your search to see, if there is really nothing related to your question. There isn't? Try searching some more! There really isn't? Ok, then go ahead and write your post. But be sure to read the following 8 rules before you do so!

And what to do, if you have an idea? Go the same way you should do for questions! See, if anyone else already had the same or a similar idea. You can't find anything? Really sure? The go on with researching about the topic. Don't just write something like "Wouldn't it be cool to..." or "I had the idea, to...". Research the topic you want to talk about pedantically. How do other projects (possibly in other languages or on other operating systems) solve the issue? Is there anything similar out there? Think about other users needs. Is this something especially for you? Then start writing a so called proposal. Choose a descriptive subject for your post (not just "I have an idea" or similar). Start writing a specification: What is your problem? What is your idea to solve it? How does that fit into the project? What is necessary to do it? Be verbose with all this! In most cases other people have a completly different perspective on the whole situation.

3. Getting used to it

A very important point before you start being a "contributor" is to get used to what you are working with and what you are talking about. You propably never used some of the tools that are commonly used in the project or it uses different tools than those that you are used to. Get used to those tools and more important, get used to the project itself. Knowing all the processes that are implemented within your community is an important point. Being used to the tools they use is even more important.

One of these important tools is GNU patch, a tool to apply differences (commonly called a "diff") to an existing version of code. Generating a patch is commonly done with the GNU tool diff. If you want to supply a patch for some code, you will propably need this tool. A lot of projects use so called "version control systems" to store their source code. The most common programs here are CVS and its newer brother SVN. Get used to these systems and make active use of them! Both systems allow you to "check out" a certain version of the source, manipulate this and automatically generate a diff for your changes.

If you already did this, go ahead and read the next 7 rules!

4. Don't overrate yourself

You are a cool and geeky person. You do development for years and in your environment you are one of the smartest. That is great. But do not assume that this also applies to the project you want to join. Open source is usually performed by people that are heavily interested in the topic, which are sometimes a lot smarter than you and who most propably have a hundred times more experience in the specific topic. Keep cool and better be shy than snobbish. Think about answers you get from members of the project, even if they look stupid to you at a first glance or if they sound rude. Research the topics people are talking about before writing an answer. Take responses to your requests seriously, although they might sound illogical to you.

5. Acting means Karma

As said before, Karma is a sensible value, which depends on hundrets of factors. One factor is acting contrast to talking. If you have an idea for a project and you are capable of realizing it: Go ahead and write a proof of concept. If you need a feature, you will propably do it anyway and use your patch for personal use. If you have it working, goto rule 2 and attach your patch to the proposal you wrote! Still, before you act, go ahead and read the following 5 rules!

6. Be friendly and open

The most open source developers you will be dealing with, will propably do open source for years. Those are already stressed by users expecting something wrong and by new developers who do not stick to these rules, you are just reading. Remember this, when reading their emails. These guys are not unfriendly or rude, they are just busy and annoyed. You will come to a state, where you have to read 20 mailinglists with thousands of posts, keep an eye on a large number of code lines, intermediate in many discussions and interact with a lot of differnet people. When reading emails, just take the objective essence of the words you are reading and ignore the tone you might feel to experience.

7. Flaming is bad

This rule is almost the same as rule 6, but it is still very important. Read every conversation carefully. I know the feeling quite well, if you think, your conversation partner "is an idiot". He is not! There are no idiots out there. He just has a different view on the things that you have or has a different technical background. Stay cool, think about your reply for some minutes/hours/days and write it, when you don't feel angry anymore. Try to state your points in polite words and explain in detail, why you are of a different opinion. If you still feel anger comming up while writing, save your reply and review it later again. Flamewars are a really bad thing and polute the communication channel of your project. They will definitly not stop occuring but that's the way it goes. The only thing you can do against this is not taking part in them.

8. Respect foreign code

Every piece of code you will see was written for a certain purpose. If you browse other peoples code, you will often think "WTF...". Don't change the code instantly to work the way you personally expect it. Get in touch with the developer who wrote the code (e.g. using "svn blame" - see rule 3). Discuss your views with him. Don't do that in public, as long as this does not affect a large portion of the project. If it does, refer to the general communication system of your project and state the issue there. Remember rules 2, 3 and 4 here at any rate. If you cannot decide, if an issue belongs there, get in touch with people you already know of the project and ask them for help. If you are kind and describe them, what you want, they will help you for sure.

9. Do not expect anything

Open source usually means working on voluntary basis. These people are (mostly) providing free software, so they are not making money with their hands work. They are doing so because of differnet reasons. Some are just idealistic, others simply want to share something, some want to profile themselves, others want to make money with the services they provide in addition and even others have everything in together in mind or even other reasons... Whatever their intention is for doing open source, they are doing it for free. Keep this always in mind, whenever you issue a request to them.

For example "feature requests" are a nice thing. They give developers an idea of what they might properly need, too. Nevertheless, most open source developers will only implement features they either need or they see an interessting technical challange in. Don't be annoyed if they refuse to implement a feature you might need. It is their clear right to refuse it, until you pay them money to do so. If a feature request is refused or not implemented in the time frame you expect it to be implemented in, go ahead and implement it yourself our consider paying a developer for the implementation. Open source developers also need to make a living and will most propably not refuse providing a patch for you for a givin sallary. Anyway, they might still not include your idea into their project or implement it in a different way. Don't be annoyed! It is their right to do so! Try to live with their conclusion or try to convince them to do it differently, but always remember to stick to the previous 8 rules, when doing so.

Whatever is described before, always reconsider your idea for several times. To expect anything from an open source developer is not the way it works, usually. Doing it yourself is what is common.

10. Learning is everything

The most important idea behind open source is to learn. People provide their sources in an open way, to let other people learn from it and to learn from other peoples contributions. The same applies to any knowledge provided about the project. Just look at this article and think about why I may write it? Correct, because I want to share my experience with the open source community with anyone who is new to it and because I want to get feedback from others, to see where I still might have weeknesses and which points I did not consider, yet.

Be sure to learn something from every line you read, might it be code or conversation. You can learn from anyone out there and if it's only how you should not do something...

--

While writing down these 10 rules, which I consider very important to read for every new open source developer, I already have more rules in mind. But let's just stay with these 10, to give a starting point. If those other things in my mind turn out to be a really good addition I will add them later on. We'll see. Thanks for any feedback and I hope this post will be useful to every newbe...

Kore also advised me to refer to How to ask questions the smart way, which reminded him about this post, while reviewing it. I did not read this article before (but maybe some similar), but it definitly looks relevant. If you have more resources, don't hesitate to leave a comment!

If you kept an eye on Planet-PHP during the past days, you will have seen a discussion emerging about the sense of doc blocks and documentation in general. Travis Swicegood states a quite interessting point of view. His main point is, that program languages themselves are declarative and that it is somewhat stupid to describe the purpose of a method in plain english, if it has been already described by the programming language itself. Although I never thought in this direction so far, I can see a valid point here. Partly.

I basically agree with Travis, that programming languages are declarative and (for the usual case) you shouldn't need much documentation for a class, if you name your methods and attributes properly. At least for an experienced programmer, the names should be obvious in most cases. But at least in PHP we have some major issues, which are modelled in code and are not obvious from the outside:

The most obvious thing are exceptions. Unlike Java, PHP does not require that an exception is either caught or the method is declared to throw it again. If you are going to use a programming libraray, you therefore have no possibility to see, which method throws which exceptions, without proper documentation. Another point are read/write only properties. Since PHP does not have a modifier for this so far, you need to go the way of interceptors. Properties which are "declared" using overloading are not as obvious as real attributes are, because they simply are not a declarative construct of the language itself. You therefore need documentation here to mark those up for the user.

But even if you neither use exceptions, nor interceptors to define properties, you still have a lot of cases, where pure naming is not sufficient to make a foreign user see in 1 glance, what happens. Simple things like the classes that are used in realtion with another class are often not obvious. Just think in matters of the factory pattern, dependency injection and similar. Additionally, if you only have the code itself, navigation is quite hard, if you have a large code base. Browsing directory structures to look for what you are searching is not fun, especially, if concepts are used, that you are not familiar with, yet.

Another (and propably the most important) point is simply the difference between people. I'm doing PHP for over 6 years now, I've dealt with a lot of libraries in PHP and have developed many applications. I'm heavily affected by what I've done and I've been inspired by a lot of people and experiences. But you are different! Are you sure, that my thoughts are as obvious to you as they are to me? No, you never can asure that. And that's a major point, why I will have to explain my thoughts to you in a more complex syntax than PHP to make you understand the overall concept behind my doings. This is quite natural and will not change any time soon, because even if programming languages are declarative, they only hava a very limited syntax. Surely you can describe all that in a programming language, too (you do! what else is your complete code base than your concepts and thoughts written down?). But to understand it all, you would need to read the complete code and not only the prototypes.

I think I made my point quite clear so far. But Travis still has a valid point. Inline API docs are not, what he is looking for in the matters of "documentation". I agree with him. No, I'm not contradictory, but in the matter of my last paragraph, people are simply different. While I consider inline API documentation an important part of any code, because it simply gives me an overall reference of what is available, I don't look at in the first glance.

While thinking about Travis matters, I analyzed my own way of working with documentation. When I start with something new (a new library for example), the first thing I want to know is "How does this work in general?". I'm sure a lot of developers have the same feeling and don't want to dig into API docs for hours and hours, before they have the big picture and understand the overall concept.

So, what is basically needed to get started is a tutorial. I consider tutorials the most important part of any documentation. A simple step by step introduction to a practical usage example gives you more than 1000 lines of inline docs when getting started with something new, because you gather the main points you are interessted in with very few learning effort:

• What is this?
• What can I do with it?
• What is the overall concept behind it?
• How am I expected to use it?

These 4 questions reflect the main information I typically want to have when digging into something new and I actually cannot imagine anything that can help me better than a tutorial here.

Ok, after reading the tutorial for a specific component, what comes next? The next step is to actually face the problem I want to solve using the library. Yes, that is basically what I want to do, solving a problem. I usually start copying some code from the tutorial, which I consider valid for the solution of my problem. Now I have to adjust that piece of code to suite my needs and make it do, what I actually want it to do. At this point API documentation enters the game. What I need is a reference of a specific class or method, to see with 1 glimpse, what I can do to adjust the behaviour. The most important questions now are:

• What are the options of an object and how do they affect the objects behaviour?
• What are the parameters of a method and how do they affect the behaviour of the method?
• What are related classes and methods, which could propably solve my problem easier or in a better way?
• Which side effects will I have to expect, if I use this class / method?

While the first 2 points should mostly be covered by the code itself (you know, programming languages are declarative), the latter 2 are mostly not. They show another 2 important points of API documentation: The relation between classes/methods and some portions of the background information, that is usually hidden somewhat deep inside the code.

So far so good, I managed to realize what I wanted to achieve. If I reached this point with reasonable time effort, the documentation of the project seems not that bad, does it? What comes next? I propably will not use the same classes I just used very soon again. But the time will come, when I come back for one of 2 reasons:

• The code I've writen needs maintainance
• I need to solve a similar problem and want to use the library again

What is different now in contrast to the first time I needed the documentation? I already have the big picture of the component in mind. I also have some working code at hands, which was written by myself and should therefore be understandable for me (inline docs help! ;). The tutorial might be helpfull now, to recall some facts. But more important are the API docs now, again.

So, why am I telling you all this? Basically to show you my view on the documentation issue. I agree with the fact, that API docs are not the solution to all of your problems. A well written tutorial helps much more in the first steps, than any API docs can do. And I think that is basically the same point Travis mentions, when he says "Give me a unit test any day over a three paragraph docblock". Exploring new terrain by example is much more effective than digging into pages of API description. But that does not mean, API docs are useless. They are very important for the further steps and should solve the issue of the limited declarativity a programming language has, due to its limited syntax.

Finally I'd like to refer to the documentation of eZ Components. I think we manage very good to provide all of the named. For each component we have different documentation forms online. A tutorial for the main functionality of a component exists (for example the ConsoleTools tutorial). Beside that, we have additional code examples shipped with each components source, for people that prefer reading PHP over English. ;) The complete source of eZ Components is inline documented and the documentation is rendered online (e.g. ConsoleTools). The API docs are enhanced by a lot of usefull features, like a special markup for the most important classes and some example code in the class docs of. Also quite nice in my eyes is the linking between tutorials and API docs, which helps you to get detailed information about a specific class or method right from the tutorial with 1 click. Finally, especially important for Travis ;), eZ Components are fully unit tested.

Is there anything more you would expect? Tell me, I'm currious! :)

The German "Linux Magazine" asked me a while ago to write an article about eZ Components for their special edition "Scripting 2.0" (dedicated to scripting languages). They published a shortened (and somewhat rephrased) version of the article online, as a teaser (German, of cause).