Getting started with Maemo Garage

This page describes how a Maemo Garage project might start up development. It is important not to achieve analysis paralysis with a project. It is important to "release early and release often" as the credo goes. Releasing source tar balls or making frequent commits allows others to see the work that an initial project admin is attempting. The release and commit work may generate additional interest from other developers. They will want to join the project.

(!) Some degree of control is required in a project. However, many projects have failed if the primary leader on the project is overly controlling. The project leader needs to "let" others help within reason of course. Perhaps one of the high profile project forks has been the Mambo project. You can read about what happened by searching for "mambo split" in google without the quotes. Essentially, a release of Mambo was used to start the Joomla Project. Establishing clear project objectives and other cultural issues may help keep a project from forking into splinter projects.

http://m770cias.garage.maemo.org/images/maemoGarageStartUp/example_repo_pic.png

Overall this page will cover the picture above and some of the ideas to use with other parts of the gForge project hosting platform. Remember these tips:


 * Start committing code to project's repository.
 * Work on small areas of the project's code so others see activity.
 * Once you have a release or a sample screen shot, publish a minimal web page to generate interest in the project.
 * Advertise for other developers. You really do not want to try and do all of the project alone if it is a large project.
 * Eventually think about gForge features to implement.

Page Status
(!) Status: Early Draft: A fairly clear SVN creation is now available.

Hosting platforms
There are a number of project hosting platforms available for project development, some of them are tailored for development in one language. A sample list of project hosting platforms follows.


 * Source Forge.
 * Source Forge Enterprise is a commercial version of Source Forge for internal projects.
 * Berlios
 * GNU Savannah
 * gForge is used for Maemo Garage.
 * gForge Group is like gForge but has commercial support and other options.
 * Launchpad is a platform used by the Ubuntu distribution and other projects.
 * Recently Google Code has started to host open source projects.

The idea behind these forge related web sites is that when a project has been approved and created by the forge IDE, a number of project administration and publication tools are made available. All of these tools operate in a consistent way through from project to project that is hosted by the same forge IDE.



The gForge group has provided permission to show this concept image of forge related IDEs. The concepts presented on this page will follow a similar flow for all of these forge related IDEs. If a person stops and understands all the features in one of these forge IDEs, then it almost appears magically what they do for a project. Essentially, the developers can focus on the content of their application while the forge IDE establishes the project infrastructure. That takes a large load of the group with an idea for an open source project.

Project Approval
There are two steps in creating a Maemo Garage project. The first step is that you must have a user account with the Garage. The Garage user registration page can be found at the top of Garage's home page. The second step after logging in is to click on the register project page. You will find this link at the top of your developer's home page.

The table above shows the kind of requirements that the Maemo Garage requires in order to register a project. You may be sucessful in aquiring project space if you remember the text on the home page of the Garage, "This site is meant for hosting various software projects related to the maemo developer platform." Each project must determine these settings for themselves.

Establishing SVN
One of the most difficult challenges of a new project is how they will set up their Revision Control System, RCS. The Maemo Garage uses Subversion for the RCS. Of all the RCS systems available Subversion may be the most ideal for the types of projects that the Garage intends to support. Perhaps the nicest aspect of SVN is that the book describing the system is developed using SVN here. Most of the first chapter will be nice background information. The Maemo Garage takes care of all of this for you when your project has been approved and created. The last section called "A Quick Start" will be the most informative.

(!) Note that the developer's directory was on a Samba server. Although the MS Windows has evaporated from the house, the old directory structure that allows drive letters be mapped to Samba shares remains. ;-)

The above example shows the final target that I'd like to achieve. There will be missteps along the way. However, a picture or map of where the m770cias project is going may be helpful to understand the example commands.

TODO describe each directory's use. This design reflects the projects mission.

Create A Proxy
The first thing that a project admin needs to do is create what I am calling a proxy of your desired SVN repository. The proxy allows a developer to seed the repository. The proxy is "thrown away" once the proxy has been used to "boot strap" the repository. There is another way to establish the repository. You can also perform an svn checkout in some directory on your development host. After the check out is performed additional files and directories are added as your project dictates. Perhaps one advantage to the proxy use is that a great deal of experimentation can occur before the initial import. Another advantage of the proxy method is that it may support the transfer of a project from one location into the Maemo Garage. Choose the method of establishing your repository that meets the requirements of your project.

The m770cias project is quite simple in its objective. m770cias is simply a place to work on images for the wiki. Moreover, there is a desire to collect some of the scripts that are floating around the Internet. So the proxy for m770cias has these attributes.


 * The proxy uses the recommended branches, tags, and trunk higher level directories.
 * The proxy uses the trunk directory to create the images and scripts directory.
 * The images directory has the very first collection of images created in the usbnet directory.
 * The scripts directory has been created.
 * The scripts directory has a source and test directory. If possible the test directory will contain some sort of xUnit testing  scripts.

Truly m770cias is a simple project but it may help a more complex project understand where to start. The type of programming language may drive the configuration of the application and initial repository design. There is a Google engEDU Video " Wikipedia and [MediaWiki"] that just touches on how Wikipedia is using branches to release their software more frequently. So the three higher level directories were created based on their potential use in the future. Again the m770cias project is a very simple project so creating a branch for parallel development may not be required. However, it would be a real mess to cleanup later if branches were required. Tags are essential to releasing related files for a specific version of an application.

Create The Maemo Project Repository
The developer has used tools on his local development host to create a project repository layout. The project's intent or application development tools may drive how the repository is designed. After all the analysis the project repository is ready to be published on the Maemo Garage repository server.

The svn import command is issued on the proxy repository as the above example shows. Please note that the svn command was issued all on one line but was split on several lines without the continuation character for clarity in this tutorial. Here's things to note in the command


 * The svn command is followed with an operation. In this case it is import.
 * The Maemo Garage user is supplied with the --username option.
 * The absolute path to the proxy was provided via.
 * A secure https URL points to the repository location on the Maemo Garage repository server via.
 * Each svn operation allows a comment. This comment is supplied with the -m svn option.
 * The Maemo Garage password is asked for before the proxy repository is imported.
 * Finally, the svn command reports what it is doing.

Success! The first revision and the intial repository of the m770cias project is alive and well and available for others to freely use.

Bypass The Proxy Creation
There is an alternative to using a proxy repository directory described in the Create A Proxy section of this document. If you just want to get going with your project, then you may want to use these operating system and svn commands.

These commands will create an empty directory on the developer's host computer. From there as each file or directory is created, svn add, and svn commit commands would be used to establish the repository. Perhaps the choice here is one of style. With this method, a developer could document the choice of each directory and file verses the svn import's one comment covering all the directories and files in the initial import command.

Maintain Commits List
As you add each developer to a project you need to remember step two of the add process. gForge and other Forge project hosting platforms create various mailing lists for you. One list is the commits list. The commits list allows all project developers or other interested parties monitor project activity. If the project admin forgets to do this, then you receive authorization email notices.

The developer's files actually made it into the SVN repository. This is just a friendly reminder that you forgot to add the developer to the commits list. The commits list is one of the things gForge provides you for free as part of its IDE. The mention of the commits list is provided in one of the earlier project approval emails that you received. The list of email messages are


 * New garage Project Submitted
 * garage Project Approved
 * garage New Mailing List

The title of the commits list message currently is called garage New Mailing List. Save this and the other two email messages as part of your project records. The "Mailing List" email message is especially important because it also contains a very long Garage system generated password. The password is for the GNU Mailman mailing list software that is used as part of the gForge platform.

(!) NOTE: Some spam munging has been performed on key fields above.

gForge still provides you with some degree of control over who gets to do what. Some developer's may not have initial SVN write access so gForge and other forge systems allow you to pick and choose. The initial admin also has to gain the trust of developers that are being added to a project unless their intent is already known. There are times when a ban may be required. The GNU Mailman software provides these support options. Additional user and developer lists may be developed as your project matures. Forum support may also be an option. For each new developer then, the project admin will want to use these settings:


 * Select the Accept radio button for any held messages.
 * Check the Forward messages box.
 * Check the Add developer box.
 * Select the Accepts radio button on the sender filters
 * Eventually change the email list password to something easier to remember that is not a dead give-away.
 * Kill all the private email messages in your private emails. ;-)

Finally, click on the Submit All Data button. Your project and hopefully the team's project that you are mentoring is underway!

An example of a clean GNU Mailman commits list screen is shown above.

Establishing The First Developer's Working Copy
So let's review our progress so far. The first step was that a Maemo Garage project was approved. The second step was that an initial subversion repository design was created. The third step was that the subversion repository was created on the Garage repository server by an svn import command. The fourth step was that project's commits list was adjusted for the first committer. It is the example project, the first committer also happens to be the project admin. Now that all the initial project implementation has been performed we're ready for the developers to get to work.

. ... ... ...
 * -- m770cias
 * |-- branches
 * |-- tags
 * |-- trunk
 * |  |-- images
 * |  `-- usbnet
 * |      |-- usbnet_concept.xcf
 * |      |-- usbnet_concept_800.png
 * |      `-- usbnet_concept_800.xcf
 * `-- scripts
 * |-- src
 * `-- test
 * -- tmp
 * `-- m770cias
 * |-- branches
 * |-- tags
 * `-- trunk
 * |-- images
 * |  `-- usbnet
 * |      |-- usbnet_concept.xcf
 * |      |-- usbnet_concept_800.png
 * |      `-- usbnet_concept_800.xcf
 * `-- scripts
 * |-- src
 * `-- test

Let's note several things about this directory tree shown above. It's not a complete tree. All kinds of fun things are located in the Nokia770 directory that is above both the tmp and m770cias directories. The tmp directory was the proxy repository for the m770cias project. The directory tree is a little ahead of tutorial but shows some important points about creating a proxy.


 * The person that is responsible for establishing a repository for a project must keep the initial proxy separate from the working copy.
 * The proxy is not destroyed until a checkout occurs. If the proxy has the only functional copy of the project's files, then you should have a backup of them and you should perform a checkout before deleting the proxy directory.

svn checkout  Anonymous checkout command.

svn checkout --username dr_kludge  Developer checkout command.

Each project has an SCM link. The SCM page presents both the project's anonymous svn checkout command and a project developer's checkout command. These two commands have shown above with the developer's name added into the command.

&#91;drkludge@bagheera ~&#93;$ cd /home/edrive/nokia770 &#91;drkludge@bagheera nokia770&#93;$ pwd /home/edrive/nokia770 &#91;drkludge@bagheera nokia770&#93;$ svn checkout --username dr_kludge 

The big day has come and the developers are ready to take off. Note serveral things with the sequence of commands.
 * A working copy can be placed anywhere on a developer's file system. The developer used the cd command to move out of his home directory into a special nokia770 directory.
 * The location of the developer was checked with the pwd, print working directory, command.
 * Finally, the svn checkout command was issued. Note that the svn command will create the m770cias top level project directory for the developer and that a prior make directory command was not issued before the svn checkout command.

Now the devloper uses his favorite tool set to operate on the the checked out copy of the repository as if it was any other source code directory on his host development computer. In this case, Gimp could be used to see if the both the usbnet_concept_800.png and usbnet_concept_800.xcf files were functional. If so, then the nokia770/tmp/* proxy can be removed.

Daily SCM Workflow
In a way, svn can be kind-of dull with only one developer on the project. The following lists the procedure that developers should become used to for all Source Control Management, SCM, controlled projects that they are apart of. Each time that you are ready to start work on files in a project directory an svn update command should be performed.

svn update At revision 11.

svn update will provide file change information on all the files in the repository, when multiple developers are working on a project, In the example above, svn update shows that no files have changed. If files were added or updated, then you would see a series of file names with an A or U respectfully. Since there is only one developer on the project, there is no exciting news from other developers as they are making progress on the Maemo Garage project.

svn add info* A (bin)  info_graphic_v2-66p.png A        info_graphic_v2-66p.png.readme.txt

After a new file or directory is created, the content can be placed under repostitory control with the svn add command. As noted above in the svn add command, wildcards can be used to add multiple files or directories. In the example above, the output means new files on the developer's working copy of the Maemo repository has been added for the next commit cycle.

svn commit --username dr_kludge /home/edrive/nokia770/m770cias -m &#039;Publish gForge image along with permission .txt file. This closes &#91;#87&#93; closes &#91;T96&#93; and closes &#91;T97&#93;&#039; Adding (bin)  www/images/maemoGarageStartUp/info_graphic_v2-66p.png Adding        www/images/maemoGarageStartUp/info_graphic_v2-66p.png.readme.txt Transmitting file data .. Committed revision 12.

Finally, the local working copy of the repository is published with the svn commit command. Once a developer sees the final, "Committed revision ##.", the local files that were added or updated to the working copy of the repository have been committed to the Maemo repository. If other developer's are using the project or tracking it anonymously, then the next svn update command will show these new files in their copy of the Maemo repository.

Trackers and Tasks
The gforge platform provides a project with trackers and tasks. At present not all the gForge modules are installed. This is a choice of Nokia on what they feel they can support. If the admin > Edit Public Info > Check the "Use svntracker 2 Plugin" was was installed trackers and tasks could be closed automatically with the svn commit command. If a string similiar to this one, 'Publish gForge image along with permission .txt file. This closes &#91;#87&#93; closes &#91;T96&#93; and closes &#91;T97&#93; ' is used in an svn commit that has the gforge SVNtracker plugin, then gForge will automatically close both the trackers and tasks. The ` &#91;#NNN&#93; literal strings operate on tasks. Note that gForge prints this information in square brackets at the top of each tracker page. The gForge tasks are cloced with the &#91;TNNN&#93; literal strings. You can find some more information here in regards to the original CVSTracker plugin. A version CVSTracker was created for SVN.

Without this plugin what do trackers and tasks buy a project. Trackers provide estential communication between developers and their users. If a user discovers a software defect then trackers allow the user to report this to the project developers. A project will have to spend some time defining categories for their trackers. The trackers must be closed by hand once the bug has been checked in and published with the File Release System. As an alternative, the tracker may be closed without any action. Sometimes a project's users do not know where to ask a question so they use a tracker to do so. If a great number of these questions occur in the tracker system, then the project should review the use of the gForge forum features.

Tasks on the other hand can be busy work for a project. Tasks can be used as an estential communication tool but the project developers are both the creators and the closers of the tasks. Both the Eclipse svn project and the Apache project may provide insight into how to use tasks. The Apache foundation uses a very formal project birthing process. Likewise, all Eclipse projects go through a similar process. These projects show a balance of how to use tasks so that you are not a slave to them. The projects set up milestones or deliverables. You can achive the same thing with tasks. The tasks layout a plan for your project. They also might generate interest from other developers. The downside is that you have to update each task with a percentage complete and eventually close the task when completed.

The m770cias project created a tracker and related tasks to show an example interaction. First the imaginary user request was created. The tracker asked for a nice concept picture of forge related IDEs. Next three tasks were established to meet this tracker. The tasks provided an example how a major change to an application can be broken down to show progress on the Request For Enhancement, RFE. The first task seeks approval from the gForge group to use an image. [The next task shows progress on commiting the image to the https://garage.maemo.org/projects/m770cias/ m770cias project's www directory. The final task tracks the linking of the image to this page. Also note that there is a "Build Task Relation button" that can be used to link the tasks and trackers together. For one little image on a web page, this can be a great deal of overhead. On the other hand, if several developers or project members are available, these tasks show how a tracker can be split over multiple resources. Just as you can make your project go no where with over analysation of issues, likewise, a project can be ground into the ground trying to close busy work features of the IDE. Please use tasks carefully.

Creating A Web Site
As one of the communitation tools, the project developers decide that they finally need a web site for their Meamo Garage project. The source code development has been in high gear and there are screen shots and other useful end user information to publish. Each of the open source projgect forge IDEs provide a different way of creating a project web page. The Maemo Garage uses a gForge plugin for this purpose. This simplfies the repository adminiatration for Nokia Corporation.

&#91;drkludge@bagheera m770cias&#93;$ tree . ... ... `-- www `-- images `-- maemoGarageStartUp |-- example_repo_pic.png |-- info_graphic_v2-66p.png `-- info_graphic_v2-66p.png.readme.txt
 * -- branches
 * -- tags
 * -- trunk
 * |-- images
 * |  |-- flasher
 * |-- scripts

The web site is easy to establish. All that has to happen is the creation of a www directory under one of a project developer's working copy. This is followed by the normal svn add and svn commit commands. Often an image directory is created for a web site. You can see that an images directory has been established for the m770cias project. At present the project is missing an  page, but the project is still looking for a web page designer. ;-) The web site is that easy.  Use your favorite tools on your development host to create images and web pages, then just commit them to the project's repository.

TODO: is this statement correct? Note that the mechanism means some tools may be excluded from the web site. You will have to use static web pages because php files and mysql databases used to serve a content management system, for example, will not be hosted on the Maemo Garage site. That's not the scope of the Garage service.

Repairing SVN Mistakes
The author writing this wiki page made a bunch of mistakes while creating the m770cias project. That's the nature of open source or editing wiki pages. Do not wait until a file or page is perfect. If a developer or wiki page author applies the "Release early and release often" open source creedo, then the world gets to see your mistakes and your good stuff alike. Moreover, the world gets to see project team members work things out. This is a far cry different than closed source applications. Typically a slick marketing department airbrushes out all the nasty wrinkles in a project of software release. And so the m770cias project willing bares all to the world. ;-)

&#91;drkludge@bagheera m770cias&#93;$ pwd /home/edrive/nokia770/m770cias &#91;drkludge@bagheera m770cias&#93;$ tree . `-- www |-- flasher |  |-- MAC_address.png |  `-- serial_port.png `-- images |-- flasher |  |-- MAC_address.png |  `-- serial_port.png `-- usbnet `-- usbnet_concept_800.png
 * -- branches
 * -- tags
 * -- trunk
 * |-- images
 * |  |-- flasher
 * |  |   |-- MAC_address.png
 * |  |   |-- MAC_address.xcf
 * |  |   |-- serial_port.png
 * |  |   `-- serial_port.xcf
 * |  `-- usbnet
 * |      |-- usbnet_concept.xcf
 * |      |-- usbnet_concept_800.png
 * |      `-- usbnet_concept_800.xcf
 * |-- scripts
 * |  |-- src
 * |  `-- test
 * `-- www
 * `-- flasher
 * |-- MAC_address.png
 * `-- serial_port.png

1 6 directories, 14 files &#91;drkludge@bagheera m770cias&#93;$

There are several things that went wrong with the repository. The first issue is that the www directory was originally placed under the trunk directory. The gForge web site plugin expects the www directory at the root node of the repository. The second issue was once that the correct www directory was established, the intermediate images directory was not created. So the whole www/flasher section needs to be hacked out.

TODO show the cleanup of the working copy with the svn commands.

svn Pointers and Environment Variables
TODO show the .svn directory that makes it all happen. TODO show alternate environment variables.

File Release System
TODO: How to release packages with gForge.

Packaging - DEB
Google engEDU Video "Anatomy Of A Debian Package"

Distributing Applications through maemo extras
Extras Repository

svn Branches
TODO show how to use the svn branch feature.

svn Tags
TODO show how to use svn tags and why.

Resources

 * gForge home page
 * svn book. You can also purchase this book.
 * MS Windows SVN client.
 * CVS information for the LEAF project.
 * Google engEDU Video "Anatomy Of A Debian Package"
 * Google engEDU Video " Wikipedia and MediaWiki"
 * xUnit testing information relating to the proposed test directory

Attribution
User:DrKludge would like to thank SourceForge user Mike Noyes, mhnoyes, for his patient help over the years. It has been watching mhnoyes' handy work that has allowed DrKludge to do some of the free and open source work that he does. mhnoyes' mentoring has also allowed DrKludge to contribute some of the things that mhnoyes has taught him to the development of this page. It is with great gratitude that DrKludge mentions Mike.

Freenode user kikov was very helpful in understanding the commit tracker and task update system.