deephacks

I have spent some time writing a foundation for Open Config Developer Guidelines. At the moment this is a very early draft summary of my own experience, gained through years as a software developer. A lessons learned if you will. I do hope for more people helping me on this mission

Why are developer guidelines necessary? At first it may seem as a smart-ass/dictator thing to do, trying to write people on their nose. This is far from the truth.

First, coding is a team effort. Developer guidelines are the pride and identity of the team, explaining their philosophy for collaboration and getting things done.

Second, the power lies in hands of the team, free for developers to adopt their own styles and change these guidelines together, as a team. There is no such thing as “dictatorship” in this regard, tyranny and arrogance pretending to be a democracy will turn people off.

The purpose of developer guidelines is to encourage the team to maintain a certain level of consistency and quality throughout all aspects of the project. Having different ways and opinions of achieving similar things cause confusion, inconsistency, and in the end, segregation within the team. This must be avoided, the team cannot afford loosing focus and good contributors in frustration and agony.

Do notice the emphasis on “guidelines” here, there will always be exceptions to every rule. Developers are expected to be thoughtful enough to care and take appropriate action (within reasonable boundaries) when these do not apply, maybe providing notice to the team of anomaly or ambiguity.

Individuals should not be afraid their opinions. But sometimes this cause strong philosophical disagreement to occur within the team. When this happens, the team accomplish consensus through voting. Individuals are expected to show good judgement resolving such conflicts, providing relevant justificating arguments from their point of view. If the conflict is resolved favoring a change of direction, individuals +1 voting for the proposal are expected to help making the change a reality.

The satisfaction of creativity is an energising motivator not to be underestimated. The team should feel proud of their creations, not frustrated by overly-constrainting rules.

This is work in progress and I sincerely invite anyone to participate. Comments and feedback on latest Open Config Developer Guidelines are more than welcome!

The Open Config website is live and kicking on http://openconfig.deephacks.org!

Documentation is something that most developers fear/hate and some of us usually avoid it til the end of a project. And im not talking about, the more mandatory, javadoc. *Ahem*

However, open-config need a presentation sketch for readers (and potential contributors) to learn about the project, allowing them to form an immediate first impression.

I dont want (and cant) document everything before even getting started. But the plan is to have a clear and concise mission statement, brief list of planned features, the most fundamental development guidelines and principles, high level design and something about project governance. I will do this before start coding, because I do not want to worry about it (too much) when im “in the zone” .

I recently found out about docbook, which btw is highly praised by the open source community, im actually a bit surprised i did not stumble on it in earlier. Docbook allow writing content decoupled from the presentation-view, using XML files. These XML files can then be transformed into navigable HTML pages, PDF, XHTML, man pages etc. Sweet! The syntax is a bit complex but since it is based on regular XML i can probably use an editor, with autocompletion and nice GUI, to help me out.

Docbook can also be easily integrated into maven (well, i had to spend a few hours on it) using docbkx. This is important because documentation must be tracked by strict version control, a wiki is far too weak in this regard. Having documentation in the same GitHub repository as code makes it easy to update since commits can include documentation changes and thus remain up-to-date with latest development. Documentation can also be branched along with code releases.

When changes are made, simply upload the latest maven-generated HTML and PDF to the project website.

The most important project artifacts can now stay in (almost) perfect sync, no matter what medium readers wish to view it on. No more excuses for doing late documentation… yikes!

Ahh! Sweet taste of freedom!

Every step taken towards a working environment for producing software in the open feels surprisingly good. Knowing that your effort is not dictated by a project budget ruled by thick hierarchies of management (sometimes ignoring the culture and principles of software developers), is a relief. This may be a manifestation of my own frustration not knowing how to work the organization.

But then again, giving something back to the community is what matters and i soon have the minimum technical infrastructure to get started with the task at hand:

• blog

  WordPress have support for most features I could wish for and also a huge community around plugins and themes. I needed a neat and pretty way of posting code, so I installed a code syntax highlighter plugin. A friend of mine, Kristian Olsson, was kind enough to let me host my blog on his server. Props!

• license

  The license has been discussed in previous posts.

• version control

  Two alternatives, Git or Mercurial. The King Penguin convinced me of git. Sourceforge is close to heart but GitHub won in the end. In my opinion GitHub has cleaner wiki and bug tracking. I wish for more elaborate code review support, but the Fork + Pull Model will do for now.

• bug tracking

  I like Jira alot, but its not free. Ticking off issues at commit-time is essential, linking commits to issues, categorization and miletones aswell. All of this is provided by GitHub. One thing i havent investigated is the possibility for automatically linking mailing lists posts to bug comments. I really hope it is possible.

• wiki

  GitHub have Wiki support. It seems pretty naive to me, but the project does not need a sophisticated Wiki at the moment.

• mailing lists

  Sharing information, ideas and discussions are the most important goals of open-config. Every contributor of this project are allowed (and obliged to) expressing their opinions about open-config in the open, with decisions taken using consensus-based democracy.

  I have used Nabble in the past and liked it alot. But I also tried out groups.google.com, which is both a forum and mailing list and it just *worked* so i’ll use it for now.

  user mailing list: open-config-user@googlegroups.com
  dev mailing list: open-config-dev@googlegroups.com

I have backup and restore on lock for everything i produce from this point on, including possibility to migrate to other providers if needed.

I also need to ensure that the work I do on this project does not conflict with policies of current employer. If i am in the clear, the next blog post will hopefully clarify the mission statement of open-config.

Take-off is close…

Ok, so i did some reading on licensing and it is… actually technically interesting. My goal is to have a business friendly license, which for me (considering my limited research) boiled down to a decision between Apache License, Version 2.0 and LGPL. Both of these seem to be considered friendly for commercial purposes.

What got me a bit worried is the discussion around LGPL dynamic linking in Java. Dynamic linking occurs in runtime, for example, when you have two *physically* separate class files that interact with each other (using the ‘import’ keyword) and the JVM hooks them together in at runtime.

Anyway, if an LGPL library jar is distributed (zipped-n-shipped jar) and dynamically linked with a company’s application, the company must allow reverse engineering of their source code (which basically is the same as shipping the source code to the user). But not only that, the company must also allow the user changing version of the LGPL library jar. However, David Turner of FSF state that the user is responsible for making these changes work. This *seems* fine in terms of technical support, but really, i have no idea what it means in court.

Hmmm.. There is a lot of bureaucracy and opinions on the subject that I do not have clue about and certainly not time to investigate..

So to avoid potential headaches, my decision falls on the more liberal approach of ASL since it allow commercial closed-source companies to distribute their software under license of their choice.

As a socialist, i always knew i wanted to give something back to the community. But I never felt that strong itch or taking the time to actually start doing it. But now I think I’ve found the energy to start my first open source project, open-config, on github.

I will use this blog to post my thoughts, progress and learnings from this work.

The first step is to choose a license and im leaning towards Apache License, Version 2.0. Although im a strong advocator for open source, i do want my software to be available to anyone, even though they may be working at closed-source projects.

BTW, if you ever want to start a open source project and build a community around it, i can recommend reading the following books:

• Producing Open Source Software
• The Art of Community: Building the New Age of Participation (Theory in Practice)