Distributed Source Control systems in FLOSS communities

The final instance of the posts about the different tools used by an open source community is the core and most important part. After all software is usually ran by code. And code is what gives developers the upper hand in using the final liberties of the free software rights. The right to modify it’s code.

So how does people modify it’s code? Well there are some standard tools that allow to keep track of all the modifications of the code. These systems are called differently but you can identify SCM, or DSCM which enable developers to perform ‘commits’ on the code and keep a version of those modifications.

Here is an example, lets assume this story is being modified by 3 developers: john, patric and bob:

When I was little I had a pony.

John comes and add:

When I was little I had a pony, the pony was named katy.

John has created a new version of the story, however the previous version still exist and patric can compare the new version to the old one. The tool used here is called, diff for differential:

Ver #01 – – When I was little I had a pony.

Ver #02 ++ When I was little I had a pony, the pony was named katy.

Patric can see here where has this been modified. He can apply corrections to it by renaming the pony katy to Katy for example, and Bob could eventually see the version 02 to the new 03 version, or 03 to 01 and see how it’s different.

Code in software behave like this except it also take into account the history of the files and folders itself.

A DSCM system will usually have plugins to connect it to the web. This makes it easier for people to see and learn how the version management take place. If you ever been in sourceforge, google code, or any big open source development project you will be able to see this systems.

More to it, the DSCM could be connected with mailing lists and provide email notifications on any change happening on the source tree (what lives in the DSCM system).

Programers more involved with things like Github can be more related with how these source trees work, and how branches, and forks, take place. Github is a service tha provides some kind of social media withing the plain Git vesion control features as well as insert an Issue tracker to it.

Here comes a big difference in development, usually Git projects tend to be more distributed, while other versions of DSCM systems like Subversion, or CVS were monolitical. The difference is simple, while the code resides on your computer as well as on the system everytime you do a checkout, in git the changes are handled in a more distributed fashion as opposed to the earlier systems. This is why Git right now is the premier and favorite control.

However not all projects use git, and for the ones that don’t usually there was a level between been a commiter and being a casual programer doing some ‘hit n run‘ code. Meaning a random patch, but don’t expect to contribute again. These ‘hit n run’ programers usually couldnt submit their patch to the source tree, so a different system was used in that case. The issue tracker.

The issue tracker serves for creating and keep a track of issues, whenever is usability, documentation, testing and yes, programming bugs. A programmer that found a bug and fix it on it’s own, but holds no attachment to the project, will use the Issue tracker to report the bug and also attach a PATCH. This is the bit of code that was modified and is up for the team of developers to integrate it back into the source tree.

In a community there was a criteria to upgrade casual developers to commiters when they scored a certain ammount of succesful patches, and some other protocols were met (like signing a license code agreement) so the project can legally stand about the status of the code.

Commiters usually were required a gpg key to be able to sign their code, and be able to be approved by the DSCM system, otherwise the commit was rejected. This is also a key component of the FLOSS developer. More information could be found on their wiki stating each step of the way on becoming a contributor, but for the most part. The cycle is similar on all projects.

Advertisement

Are you ready for total KaOS?

KDE is a great desktop, it needs a good OS that knows what its doing to make it look awesome.

Marcel Gommans

      Another relatively unknown distro I recently came across is KaOS. In 2013 KaOS was created as an independent OS. It is based on the Linux kernel, although the makers still look at Opensolaris as an alternative base. KaOS 2014.04 uses pacman as its package manager. This might give you the idea that it is Arch-based, but the website clearly states that it’s completely indepentent. Let’s find out if KaOS is an undiscovered gem or if it leads to chaos…. Installation Before we start the installation, we have to know one important decision the creators have made when they started this distribution: creating an OS is about making choises. They decided to make a few decisions that can make this distro interesting for you, or not. After choosing the Linux kernel they picked KDE as the only available desktop environment and QT as their toolkit. KaOS only has…

View original post 541 more words

Getting started with Documentation

Projects in the open source world usually always in need of documentation. Bad documentation or non existent documentation is something that they have struggle to eradicate. Developers sometimes put their compilers away and dedicate some time to write about all  the classes and functions that have been written during the past few months. But this doesn’t always happen let alone be up to date.

So users, new contributors, people that want to understand the code, and want to get instant contributions, documentation might be a good area to start with. Why? Because on one side you will learn a lot about what is documented, not just the content but the style and organization. On the other side, you will actually learn about what has been documented including past functions, examples, and snippets.

Wikis are a great way to produce documentation, but if you never touched one aside from the random Wikipedia search. You should understand some key aspects of it:

• wiki language – markup of the wiki, formatting, labels, tables, images, and more
• history – each page has a history of edits, make sure to read the comments
• history differential – review changes as the documentation came to become
• editors – check out the common editors of the wiki, they can be great mentors, usually their nicks are in the history
• watch pages – provide a subscription to the changes of a page, check your settings if you want alerts by email
• styles – understanding structure, wiki books, standard labels
• comments – use comments withing the wiki to ask/add clarification
• translations – localization of the documentation is even more needed, some wikis are internationalized, make sure you learn the process to localize wiki pages, verify they are up to date.
• code highlighting – improving formatting on snippets is to add the highlight to the code to improve readability.

All these are expanded on the documentation of the wiki the project is using, usually open source projects prefer open source wikis, the most used are:

• mediawiki
• moin moin
• dokuwiki
• confluence wiki
• trac
• github/google code/sourceforge wiki

Each has their own markup differences, but in general you should understand how your formatting can become better by looking at heavy formatted pages withing the wiki. Tables, layouts, images, text blocks, menus, etc. All these elements combine to make a very boring wiki into a very appealing web-site like and easy to read and follow. Headers are a good way to break content withing the page.

Besides the technical aspect is important to communicate the work you do on the wiki to the rest of the community. New documentation is always well received and even users can comment and contribute fixing possible spelling mistakes. There are some old ways that you will need to rethink about content as you work with wikis.

Wikis are about collaboration, various people working on a single body of work. For that reason you need to be more bold and fix others people writeup without waiting on their permission. The same is expected from you, from other people modifying your work. Remember this is not YOUR work, but the work of the community. So your work is meant to be modified.

Spelling, grammar, and technical mistakes are easy to change, however more structural changes might need some leading role. For example, if a new version of a software is launched, should you rewrite the whole site detailing the new information, or should you create a new page with the new information of the new version. These topics need to be discussed on the mailing list, but at the same time, remember that changing a page is easier than deleting one. So working withing the created pages provide less future problems (since you can go back in time), than creating new ones (which only administrators can delete permanently). This is also something to keep in mind when you create new pages.

More complex wikis use extensions which improve the editing and readability of a wiki. Wikibook is an example of these, where you can add a series of pages linked as a sequence. Other great extensions are more powerful editors, media managers, attachments, rss feeds. If you want to contribute to the community, install a copy of the wiki and run test on new possible extensions that the community could benefit from it. This is another way to contribute to the community by becoming the wiki guy.

Getting started with mailing lists

Lists are core of the community.

There are 2 different way to approach this topic, the technical part of mailing lists and the behavioral aspect of it. I’ll quickly go through the first one.

A mailing list is a mechanism where a lot of email address resource to a list address to replicate the message throughout the subscribers. It can be delivered in two modes, as single email (the preferred one) as summary which compile emails from the week or month into one single email.

To join a mailing list, there are two possible process, through the list website, or through email process. The second one is usually the more common, and the exercise go like the following:

1. Send an email o the list suffixing ‘-subscribe‘ to the recipient. No subject or content necessary.
   ex. mylist-subscribe@domain.com where ‘mylist’ is the recipient
2. Expect a reply from the list asking for verification, the content of the email have a URL which you can click to verify
3. Alternatively you can reply back to the received email.
4. Expect a confirmation-welcome email.
5. Send your first email to the list to the list address mylist@domain.com

Now the behavioral part

Of course your motives to joining the list might vary, if you are looking for help, you might got to a list aimed at users or support. While if you want to contribute, you might look for dev which will focus on development, larger projects might have some qa for quality assurance.

So first lesson is understanding what information might be useful, again this depends on your porpoise and type of list you are on. But as a general rule, try to: focus on the information relevant to the reader, not to you.

In other words, avoid giving irrelevant information, although you might think that giving more information is better, too much information could make the reader hard to get to the point. So, avoid the spam-ish info. Information like your system specs could be valuable, make sure you show the issue first and compliment the main information with more details.

Second lesson is try to participate, voting, call for help, call for support, documentation, and other areas could be great first contributions to the community. More than asking where to start (although nothing wrong with this), try reviewing the project wiki, or documentation which will probably have you covered. Instead try to ask something along the lines of that information, or even better, comment on your first contribution to get some feedback on it.

Reviewing the DSCM (like git, svn) comments could become a great way to review code, provide patches, and get involved with cleaning up code. From comments on the class, function or modules, to refactoring (depending on your skill) and optimization.

If you think your skills or the code tree is too much to understand it. Make sure you can focus instead on the final product. Downloading and compiling (or installing) could provide good testing reports on ‘so called’ squashed bugs. Copy your comments to the list (QA or dev). This will only need power users (for compiling) or regular users (for regular install) and provide your own feedback.

A list might flood your inbox, so using filters/labels might be good to keep the traffic off your regular email. Reading emails even if they are not target to you is in general a good practice. Even if you don’t completely get it, it will help you understand what’s going on with the community. To accelerate these process, you can review the archives.

Scanning through months of conversations can quickly open your eyes with the way the community behaves, evolves and where is going to. Usually go to the signature of any email to go to the site of the list, like: domain.org/cgi-bin/mailman/listinfo/flisol

You would be able to identify the “About” section with the line: To see the collection of prior postings to the list, visit the (mylist) Archieve

A table containing months, type of order by: thread, topic, date and author. This will make you easily read the list, even if it might not be the best to search through it.

Learning about communities

Through my experience with developers and open source experts, I found something very curious. In the end, all I have seen are power users. Usually the computer enthusiast is divided by developers and users, however there are so called developers, but they are really users of a language. But (at least in public) they are only users of a language, their open source expertise as far as using Linux as their developer platform doesn’t exceed to the contribution part on not just their favorite language (which will probably be done on a different language) but to other projects built on that language.

The sad reality is that open source enthusiast don’t always grab the concept of a community. Usually community becomes something that is more socially accepted as a user group, even their blogs usually focus on new libraries, technologies and modules to use. Rarely is about a project community where gyrate around a source tree, with a product that is compiled and released on a scheduled manner.

So, for example, Big Joe who is a great FLOSS advocate and use PHP-MySQL for all it’s clients and do it on his GNU/Linux servers and wears a Ubuntu t-shirt and give advices on why everyone should use Linux. He has even gave talks about PHP development techniques, security on the language and gives the green light to trying new modules and frameworks for its development.

Yet Big Joe, however, has never imagine on even getting in touch with the people at PHP.net, has never even compiled the source code of the language, or know how to. He doesn’t even know who build what part of the language. In his head, he might even ridicule the idea of taking time off his clients to dedicate in such a task, as the language is good enough, for his needs.

When confronted, Big Joe admits that his knowledge of PHP would be useless that looking at the source tree is based on another language, C. However given his big and deep knowledge of PHP, he should be able to look elsewhere where PHP is proven to be the language of choice, a project like Drupal, which is a very popular CMS could present somewhere where he should feel more competent to work upon. The Drupal source code is in fact made out of pure PHP code, many hundred of lines of code.

Big Joe now has 2 problems, how will he be able to read all that source code? And where should he start?

Maybe Big Joe would feel Drupal is a waaaay too big of a bone to chew on. So he has other options. Sourceforge has hundred of projects of different size to contribute to. Projects like DokuWiki, or even lesser known projects that could use his help.

So Big Joe found his project where he can read up easily and contribute with his magnificent PHP skills. However there is another problem, Big Joe also doesnt know how to start. And here is where the real learning needs to happen. For all his years of apt-get install and tar -xzvf or unzip -r modules and libraries. He would now need to learn some base new technology.

First one will help him communicate with developers, and will prove to be the most used and is called mailman. This help him keep in touch with the whole team of developers, however he will also see other users as he subscribe to the commit list which automagically email him all the changes to the code.

The next piece of technology is the wiki, where most of the documentation to get started, as well as some design pointers are already documented on these places. Is important that he check its out while joining the community to avoid being outcast from acting far from the status quo.

Finally the big and more developer-like piece is the code repository where the commits and builds he do himself should be commited and approved. Big Joe will found a new family of activities including:

• QA, test new patches from others and give follow up.
• Managing branches, in git this could become an all day task if the project get busy.
• Verify bugs, evaluating bug reports and finding the issue is another big developer task.
• Building, having cyclical builds and maintaining the successful build is another task that give some sense of stability, coding bugs might raise some flags, that something somewhere is not really working.
• Documenting, as a user documentation is important, however as a developer, a good technical documentation can help people do their work more efficiently.

Big Joe found that contributing isn’t as hard as he thought initially, and now he has become someone with a say in a real free software project. Now Big Joe will dedicate some time to encourage people to step into this level of contribution, and maybe he could get his USER group into a real developer group and do cool stuff like a bug hunt, or a development spring.

Big Joe is very well networked withing the community and can now have some real hold on not just promoting FLOSS but actually being part of producing floss.