| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" | |
| content="text/html; charset=windows-1252"/> | |
| <title>Plugging into SourceForge.net</title> | |
| <link href="../default_style.css" rel="stylesheet"/> | |
| <meta content="David J. Biesack (david_biesack@users.sourceforge.net)" | |
| name="author"/> | |
| <meta content="pombredanne@nexb.com" | |
| name="editor"/> | |
| <meta content="Describes how you can publish your open source Eclipse Plug-In on SourceForge.net" | |
| name="description"/> | |
| <meta content="https://bugs.eclipse.org/bugs/show_bug.cgi?id=94940" | |
| name="bugzilla"/> | |
| </head> | |
| <body> | |
| <div align="right"> | |
| Copyright © 2005 by David J. Biesack | |
| </div> | |
| <div align="left"> | |
| <h1><img align="middle" alt="" height="86" src="../images/Idea.jpg" | |
| width="120"/></h1> | |
| </div> | |
| <h1 style="align: center;">Plugging into SourceForge.net</h1> | |
| <blockquote> | |
| <p><b>Summary</b></p> | |
| <p>Congratulations on taking the plunge and writing an open source | |
| plug-in for the Eclipse platform. | |
| SourceForge.net can provide a good home your plug-in, but | |
| information on how best to set up an Eclipse project there is sparse. | |
| This article is an introduction to SourceForge for the Eclipse | |
| developer. You will learn the features available to the | |
| SourceForge.net open source developer community and be guided | |
| through the process, from creating a SourceForge project to | |
| hosting your Eclipse Update site.</p> | |
| <p><b>By David Biesack, SAS</b></p> | |
| <p>October 15, 2005</p> | |
| </blockquote> | |
| <hr /> | |
| <h3>SourceForge: A site for everything open source and nothing in | |
| particular</h3> | |
| <div><img align="right" alt="SourceForge.net logo" | |
| src="images/SourceForge.net.png" | |
| style="margin:5px; width: 210px; height: 62px;" title="SourceForge.net"/></div> | |
| <p><a href="http://www.sourceforge.net/">SourceForge.net</a> (or | |
| simply SourceForge) is the world's largest open source | |
| software repository and developer resource. Just as Eclipse is an | |
| "<a href="http://www.eclipse.org/articles/Article-UI-Guidelines/v200202/Contents.html" | |
| >IDE for everything and nothing in particular</a>", | |
| SourceForge is a developer site for everything open source and | |
| nothing in particular. Similar to how an Eclipse plug-in plugs into | |
| the Eclipse framework through extensions of well-known extension | |
| points, open source projects "plug into" the rich | |
| collaboration community hosted by SourceForge.</p> | |
| <p>SourceForge is language and platform agnostic — | |
| it may be Java, .Net, Perl, | |
| Ruby, PHP, or any other software project. For each project, regardless of | |
| language or platform, a wide array of services is freely | |
| available. The project 'extension points' include server | |
| space for a project web site, your own project sub-domain, a CVS | |
| server, file release management, GNU Mailman mailing lists, project | |
| categorization, on-line discussion forums, bug tracking, secure | |
| login shell and FTP, a compile farm, task lists and even an on-line | |
| financial donation management.</p> | |
| <div><img align="right" | |
| alt="SFPDE - SourceForge Plug-In Development Environment" | |
| src="images/sfpde-med.png" style="margin: 5px;width: 360px; height: 265px;" | |
| title="SFPDE - SourceForge Plug-In Development Environment"/></div> | |
| <p>There are too many services available to cover in this article, | |
| so I present one common scenario — the creation of a new project | |
| — and I introduce features as they come into play in the life | |
| cycle of developing, publishing, and supporting an open source | |
| plug-in for Eclipse.</p> | |
| <p>You will see how SourceForge extends the Eclipse Plug-in | |
| Development Environment (PDE) to create what I refer to as the | |
| SourceForge <strong>Plug-in Development Environment</strong> | |
| (SFPDE). Eclipse provides the coding, testing, debugging, and | |
| packaging aspects of Plug-in development. The SFPDE adds the source | |
| management, distribution, collaboration, discovery, web hosting, | |
| and support capabilities. The combined SFPDE services offer a | |
| comprehensive environment for Eclipse plug-ins | |
| development.</p> | |
| <p>I will use a humble plug-in that I wrote and released on | |
| SourceForge as an example (the | |
| <a href="http://eclipseexeditor.sourceforge.net/">Eclipse Text | |
| Editor Extensions</a> ), so you can refer to a concrete plug-in | |
| project.</p> | |
| <p>For this article, I assume that you are already familiar with | |
| writing Eclipse plug-ins, and you have an idea that will | |
| revolutionize the Eclipse community: if only you had a way to share | |
| it as an open source project! You have some code to commit to CVS | |
| and would like to attract one or two open source contributors | |
| to help you polish it off. I also assume you are familiar with | |
| most of the concepts of open source projects, including license | |
| models, community involvement, patches and contributions, etc. If | |
| not, there are resources available at the | |
| <a href="http://www.opensource.org/">open source Initiative</a> | |
| (OSI).</p> | |
| <h3>Planning</h3> | |
| <p>As with any software endeavor, a little bit of planning will | |
| reduce your long-term frustration. With an open source project, | |
| you probably do not have a software manager and marketing | |
| department pushing you to release the new product, so you may | |
| actually have time for planning!</p> | |
| <p>This is an outline of an open source project's lifecycle | |
| within the SFPDE:</p> | |
| <ol> | |
| <li>Understanding the SourceForge open source Software model</li> | |
| <li>How to structure a SourceForge project</li> | |
| <li>Naming the project</li> | |
| <li>Naming the Java package</li> | |
| <li>Choosing a license</li> | |
| <li>Registering on SourceForge</li> | |
| <li>Trove classification</li> | |
| <li>Using SourceForge's CVS server for Eclipse projects</li> | |
| <li>Secure services: private and public keys and SSH</li> | |
| <li>Making a software release</li> | |
| <li>Building a web site</li> | |
| <li>Hosting an update site</li> | |
| <li>Registering with a plug-in promotion site</li> | |
| </ol> | |
| <h3>Plugging In</h3> | |
| <h4>Understanding the SourceForge open source Software model</h4> | |
| <p>Before you begin an open source project on SourceForge, be sure | |
| you understand the SourceForge definition of open source and its | |
| requirements for hosted projects. You should read and grok the | |
| SourceForge | |
| <a href="http://sourceforge.net/docman/display_doc.php?docid=6048&group_id=1" | |
| >Terms of Use</a> , and be fully comfortable with the requirements | |
| outlined there. SourceForge users assume certain aspects | |
| of open source projects, so be sure you know what the open source and | |
| SourceForge communities will expect of you.</p> | |
| <h4>How to structure a SourceForge project</h4> | |
| <p>The next step in the planning process is to get your project in | |
| order before shipping it up to SourceForge. I have found that it | |
| is convenient to create four separate Eclipse projects. Below is | |
| the layout of my projects for my sample plug-in. I named the | |
| project based on the root Java package, net.sf.eclipseexeditor | |
| (described below).</p> | |
| <table border="0" cellpadding="0" cellspacing="0" style="text-align: left; width: 600px;"> | |
| <tbody> | |
| <tr> | |
| <th>Eclipse Project Description</th> | |
| <th>Example</th> | |
| </tr> | |
| <tr> | |
| <td>Your plug-in, as an Eclipse PDE project.</td> | |
| <td>net.sf.eclipseexeditor</td> | |
| </tr> | |
| <tr> | |
| <td>Your Plug-In Feature, created from the Eclipse feature | |
| wizard.</td> | |
| <td>net.sf.eclipseexeditor-feature</td> | |
| </tr> | |
| <tr> | |
| <td>Your update site, created from the Eclipse update site | |
| wizard.</td> | |
| <td>net.sf.eclipseexeditor-update-site</td> | |
| </tr> | |
| <tr> | |
| <td>Your web site, your public documentation.</td> | |
| <td>net.sf.eclipseexeditor-web-site</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p>Some projects may have several plug-ins, each with its own PDE | |
| project. For example, solareclipse has the following project/file | |
| structure:</p> | |
| <ul> | |
| <li>net.sf.solareclipse-feature</li> | |
| <li>net.sf.solareclipse-home</li> | |
| <li>net.sf.solareclipse.jsp.ui</li> | |
| <li>net.sf.solareclipse.ui</li> | |
| <li>net.sf.solareclipse.xml.core</li> | |
| <li>net.sf.solareclipse.xml.ui</li> | |
| <li>net.sf.solareclipse.xslt.debug.core</li> | |
| <li>net.sf.solareclipse.xslt.debug.ui</li> | |
| <li>net.sourceforge.solareclipse.web.ui</li> | |
| <li>net.sourceforge.solareclipse.xml.core</li> | |
| </ul> | |
| <p>Be sure to review your project's names before committing to | |
| CVS: the project name will become the CVS module name. The | |
| solareclipse project's | |
| <a href="http://cvs.sourceforge.net/viewcvs.py/solareclipse/"> | |
| CVS</a> tree has apparently obsolete modules named | |
| <code>org.sourceforge.solareclipse.web.ui</code> and a misspelled | |
| <code>net.courceforge.solareclipse.web.ui</code> module.</p> | |
| <p>You may also find it convenient to define | |
| <a href="images/working-set.png">an Eclipse Working Set</a> that | |
| contains all your projects. This can help with restricted file | |
| searches in Eclipse, i.e. text/file searches for classes or package | |
| names in plugin.xml or web site content, in case you need to rename | |
| classes or packages. Note that you can host <strong>all</strong> | |
| your related Eclipse PDE projects within a single SFPDE project | |
| space.</p> | |
| <h4>Naming the project</h4> | |
| <p>Patterns, packages, projects have more in common than their | |
| first letter. In all cases, a good name cannot be beat. Sadly, | |
| my project name (eclipseexeditor) is not a good example. It was | |
| only after I had created my SourceForge project and worked on it | |
| significantly that I realized that ETEE — an acronym for | |
| Eclipse Text Editor Extensions — would have been a better | |
| choice.</p> | |
| <p>Your SourceForge project name will be used everywhere in | |
| SourceForge: in the Unix file system as the directory name, as a | |
| CVS root, as a component of a domain name/URL — | |
| <a href="http://eclipseexeditor.sf.net"> | |
| http://eclipseexeditor.sf.net</a>, in your project's summary | |
| page url — <a href="http://sf.net/projects/eclipseexeditor"> | |
| http://sf.net/projects/eclipseexeditor</a> , in Mailman mailing | |
| lists names, etc. In other words, choose a name that is easy for | |
| your users to use and remember and that still conveys the purpose | |
| of your project. SourceForge does not support renaming projects | |
| after their creation.</p> | |
| <p>Here are the SourceForge rules for a project name:</p> | |
| <ul> | |
| <li>It must begin with a letter</li> | |
| <li>It must be between 3 and 15 characters in length</li> | |
| <li>It can only contain only lowercase letters (a-z), numbers | |
| (0-9), and dashes ("-") or underscores | |
| ("_")</li> | |
| <li>It cannot match the name of any other project or one of | |
| SourceForge's reserved names</li> | |
| </ul> | |
| <p>Once again, remember that you cannot change the project name after its creation... so | |
| be sure you are happy with the name!</p> | |
| <h4>Naming the Java package</h4> | |
| <p>Since we are talking naming, it is a good idea to | |
| consider carefully the Java packages names for your plug-ins. Â If you are | |
| part of a commercial organization or org site that is sponsoring | |
| the plug-in development, you may wish to release the plug-in as a | |
| specific package within that name space, such as the veloedit | |
| Velocity editor: <a href="http://sourceforge.net/projects/veloedit/" | |
| ><code>org.vaulttec.velocity.ui</code></a> . Presumably, one should | |
| not use <code>org.eclipse</code> as a base package name, as that | |
| name space is reserved for official Eclipse projects at | |
| www.eclipse.org. I chose the pattern of <code>net.sf.</code> + | |
| <i><code>projectname</code></i> (i.e. | |
| <code>net.sf.eclipseexeditor</code> ) over something like | |
| <code>org.biesack</code> so that the code base will feel more | |
| "open" to other contributors. After all, a key aspect of | |
| an open source project is that potential collaborators feel | |
| welcome.</p> | |
| <p>Other projects on SourceForge have followed this example, such | |
| as <a href="http://sourceforge.net/projects/solareclipse/"> | |
| net.sf.solareclipse</a> and | |
| <a href="http://sourceforge.net/projects/lunar-eclipse/"> | |
| net.sf.lunar_eclipse</a> . Note that if you wish to follow this | |
| pattern, you should avoid using a dash in your project name, which | |
| is illegal in Java. The biggest reason to use this format is that | |
| it follows | |
| <a href="http://java.sun.com/docs/books/jls/second_edition/html/packages.doc.html#40169" | |
| >Sun's recommended package naming convention</a> of reversing | |
| the domain name. Since your domain name will be | |
| <code><i>projectname</i>.sourceforge.net</code> or | |
| <code><i>projectname</i>.sf.net</code> , this leads to a Java | |
| package name space of <code>net.sf.<i>projectname</i></code>. Other | |
| projects do not follow Sun's recommendations. For | |
| example, <a href="http://sfutils.sourceforge.net/">sfutils</a> has | |
| packages like <code>sfutils.frs</code> with no <code>net</code> | |
| or <code>org</code> or <code>com</code> prefix.</p> | |
| <h4>Choosing a license</h4> | |
| <p>SourceForge has a well-defined specification | |
| for open source projects, including a license. SourceForge requires | |
| that you use either an approved an approved open source initiative | |
| license, or a license that complies with the | |
| <a href="http://www.opensource.org/docs/definition.php">open source definition</a>. See the | |
| <a href="http://sourceforge.net/docman/display_doc.php?docid=778&group_id=1" | |
| >B6. open source license overview</a> for more details: "<cite>It is vital that you read and | |
| understand all of the terms of a license, and verify that it meets | |
| the needs of your project, before deciding to use that license; | |
| this should not be a decision taken lightly.</cite> "</p> | |
| <p>The license you select can also influence | |
| your ability to draw contributors to your plug-in. In addition, changing a license later often | |
| alienates your user and contributing developers' community. | |
| Eclipse plug-in developers may want | |
| to consider the | |
| <a href="http://www.opensource.org/licenses/eclipse-1.0.php"> | |
| Eclipse Public License</a> (EPL), an <a href="http://opensource.org" | |
| >OSI approved</a> and SourceForge acceptable license. By choosing | |
| EPL, you will be using the same license as the Eclipse.org | |
| projects, and your plug-in license will be compatible with future | |
| Eclipse developments.</p> | |
| <h4>Registering on SourceForge</h4> | |
| <p>Now that you have some of the planning done and your plug-in is | |
| complete enough for an initial code contribution, it is time to | |
| start your registration process. Naturally, SourceForge has an | |
| on-line web based registration process that guides you through the | |
| following steps:</p> | |
| <ol> | |
| <li>Hosting information</li> | |
| <li>Registering a project</li> | |
| <li>Terms of Use Agreement</li> | |
| <li>Hosting requirements</li> | |
| <li>Project license details</li> | |
| <li>Project description details</li> | |
| <li>Project name details</li> | |
| <li>Final review</li> | |
| <li>Submission completed</li> | |
| </ol> | |
| <p>There is plenty of documentation and help along the way. If | |
| you have done the suggested planning, this should only take 10 to | |
| 15 minutes. Once your new project submission is complete, it will | |
| take a few days for the SourceForge staff to process the request | |
| and create your project.</p> | |
| <p>You start by logging into SourceForge. If you do not already | |
| have an account, simply click on the <strong> | |
| <a href="http://sourceforge.net/account/newuser_emailverify.php" | |
| >New User via SSL</a></strong> link on the front page and enter | |
| your email address and a create a password. SourceForge will send | |
| an email to the address you supply to confirm it is a valid | |
| address. (If you have some spam filtering enabled, configure it to | |
| allow mail from the domain "sourceforge.net" and any | |
| sub domains). You must visit the confirmation URL in that email | |
| message. At this point, you will be able to choose an account user | |
| name.</p> | |
| <p>Next, log in using your userid and password, and then click the | |
| <strong><a href="http://sourceforge.net/register/">Register New | |
| Project</a></strong> link to begin the registration process. Review | |
| the Hosting information and the Terms of Use Agreement that you | |
| must accept before proceeding. You will need to supply some of the | |
| important information discussed above: your project name, | |
| license, a short public project description, and a longer project | |
| justification to help the SourceForge administrators understand how | |
| your project adds value or is different from existing solutions.</p> | |
| <p>Once you complete your registration, you must wait a few days | |
| for the SourceForge administrators to review your request and set | |
| up the infrastructure. You should receive an email response | |
| informing you of the project's creation when it is ready. You | |
| can check the status of any of your project requests by visiting | |
| your SourceForge home page: | |
| <code>http://sourceforge.net/users/<i>your-userid</i>/</code> . | |
| There, you can view all of your SourceForge projects. Also, on the | |
| '<a href="https://sourceforge.net/my/myprojects.php">my | |
| projects</a>' page you can see all your projects regardless of | |
| their approval status.</p> | |
| <p>When accepted, your project will also receive a unique numeric | |
| identifier, called a <i>group id</i>, used to access some project | |
| resources on SourceForge instead of the Unix project | |
| name.</p> | |
| <p>Once your project is created, the next step is to verify your | |
| project's public information in the Public Info section, and | |
| to classify your project in the <a>Trove Software Map</a>.</p> | |
| <h4>Understanding the Trove Classification</h4> | |
| <p>The Trove — or <a href="http://sourceforge.net/softwaremap/"> | |
| software map</a> — is a software categorization and classification | |
| system to organize all SourceForge projects. The software map is | |
| one of the key links on the SourceForge front page. Together with | |
| your keywords and description, the Trove makes your | |
| plug-in easier to find.</p> | |
| <p>Unfortunately, the Trove organization does not always fit | |
| everyone's model. For example, although there is a top-level | |
| category for | |
| <a href="http://sourceforge.net/softwaremap/trove_list.php?form_cat=45" | |
| >Software Development</a> , the topic | |
| <a href="http://sourceforge.net/softwaremap/trove_list.php?form_cat=65" | |
| >Integrated Development Environments (IDE)</a> — a good location | |
| for many Eclipse plug-ins — is instead under the main topic | |
| <a href="http://sourceforge.net/softwaremap/trove_list.php?form_cat=63" | |
| >Text Editors</a>. Â I recommend placing Eclipse plug-ins that | |
| are un-related to Software Development — such as the | |
| <a href="http://sourceforge.net/projects/morphine/">Eclipse RSS | |
| Reader</a> — in Trove categories that reflect | |
| their use, not their implementation technology.</p> | |
| <p>Using the software map, you will have the opportunity to select | |
| one to six, and sometimes more, project values in each of several | |
| categories: Topic, Operating System, Programming Language, License, | |
| Intended Audience, User Interface, Translations, Database | |
| Environment, and Development Status . Eclipse plug-in writers | |
| should include | |
| <a href="http://sourceforge.net/softwaremap/trove_list.php?form_cat=583" | |
| ><strong>User Interface :: Plugins :: Eclipse</strong></a> in the | |
| set of User Interface values, and under Operating Systems, you may | |
| want to choose | |
| <a href="http://sourceforge.net/softwaremap/trove_list.php?form_cat=235" | |
| ><strong>System :: Grouping and Descriptive Categories :: OS | |
| Portable (Source code to work with many OS platforms)</strong></a> | |
| . You can also use the | |
| <a href="http://sourceforge.net/softwaremap/trove_list.php?form_cat=472" | |
| ><strong>User Interface :: Graphical :: Java SWT</strong></a> | |
| category.</p> | |
| <p>Review carefully all the options to help your users locate | |
| your plug-in while browsing projects categories. See | |
| <a href="http://sourceforge.net/docman/display_doc.php?docid=12973&group_id=1" | |
| >Software Search and the SourceForge.net Software Map</a> for | |
| details.</p> | |
| <p>Note also that you must add each classification one by one by | |
| selecting the value in a drop down list then clicking the Add | |
| button to its right. You cannot select values for several | |
| categories and add them all at once.</p> | |
| <h4>Using SourceForge's CVS server for Eclipse projects</h4> | |
| <p>Now that you have a project that other's can find, | |
| it is time to put some content there. The most important | |
| content is the source code, managed in a | |
| <a href="http://www.cvshome.org/">Concurrent Versions System</a> | |
| (CVS) repository. Since Eclipse has built-in support for CVS | |
| repositories in the Team development plug-ins, it is | |
| straightforward to use within the SFPDE.</p> | |
| <p>Once approved, your project will have a CVS repository dedicated | |
| for it at | |
| <code>cvs.sourceforge.net/cvsroot/<i>yourprojectname</i></code> . | |
| For example, the net.sf.eclipseexeditor project is at | |
| <code>cvs.sourceforge.net/cvsroot/eclipseexeditor</code>. | |
| Here is my project's CVS view:</p> | |
| <p><img alt="Sample CVS project view" src="images/cvs-view.png" | |
| style="width: 407px; height: 222px;" | |
| title="Sample CVS project view"/></p> | |
| <p>You can visualize the project partitioning here: I use one directory | |
| for the PDE project source, one for the plug-in feature project, | |
| one for the update site project, and one for the web site.</p> | |
| <p>For each of your Eclipse projects, invoke the project's | |
| context menu from the Package Explorer view and select the menu | |
| Team ->Share Project. Chose CVS and complete the Share Project | |
| wizard (see the | |
| <a href="http://help.eclipse.org/help31/index.jsp?topic=/org.eclipse.platform.doc.user/gettingStarted/qs-61f_syncproject.htm" | |
| >Eclipse help</a> for more details) to attach it to the SourceForge | |
| CVS repository. If instead you are going to be joining a project | |
| that already resides in CVS, you can simply check the project out | |
| of CVS using the standard Eclipse Team operations. Â Once your CVS | |
| repository is defined in Eclipse, you can use the normal Team | |
| operations to commit your source to CVS by invoking Team->Commit | |
| from each of the project folders. I recommend keeping Eclipse | |
| metadata files — <code>.project</code> and <code>.classpath</code> | |
| — under version control so that others can simply checkout | |
| the projects from Eclipse's CVS client. Eclipse will | |
| automatically detect the project's Java nature, and build path | |
| configuration.</p> | |
| <h4>Secure Services</h4> | |
| <p>To commit files to SourceForge's CVS servers and access the | |
| shell, you must use SSH.</p> | |
| <p>This means using the <code>extSSH</code> connection method if | |
| you want to use Eclipse's built-in CVS and SSH client, or | |
| using a properly configured <code>ext</code> method to rely on your | |
| favorite SSH client. SSH provides secure communication with the | |
| server through encryption.</p> | |
| <p>If your system already has a SSH implementation, you should be | |
| able to use it. SSH implementations are available on Macs and most Unix | |
| variants, including Linux. Windows users of the Cygwin tool | |
| set can use <a href="http://www.openSSH.org/">OpenSSH</a> , or | |
| users without Cygwin and OpenSSH can try <a href="http://www.putty.nl/"> | |
| PUTTY</a> or another secure shell tool set.</p> | |
| <p>If available, SourceForge recommends using a tool set that uses | |
| the SSH2 protocol for greater security, which is the version | |
| supported by Eclipse's built-in CVS SSH client.</p> | |
| <p>You will also need SSH to copy files to your project's | |
| shell and web space. The SourceForge site help | |
| provides complete documentation to | |
| <a href="http://sourceforge.net/docman/display_doc.php?docid=6841&group_id=1" | |
| >configure SSH</a>. Â Windows users may also consider | |
| <a href="http://www.winscp.net">WinSCP</a> , a SourceForge | |
| <a href="http://sourceforge.net/projects/winscp">project</a> that | |
| provides drag and drop integration with Windows. For example, after | |
| you update your web site in Eclipse, you can open WinSCP, authenticate, then jump via a WinSCP favorite to your SourceForge | |
| project web space and <a href="images/WinSCP.png">drag files | |
| from the Eclipse Package Explorer</a> to the WinSCP view.</p> | |
| <h4>Making a software release</h4> | |
| <p>Software releases are the primary mechanism that SourceForge | |
| users employ to make downloads available software to their users. | |
| SourceForge supports a robust system for releasing your software. | |
| Released files are preserved for the lifetime of the project, allowing | |
| anyone to download previous releases — although you can hide | |
| releases if needed. Making a software release on SourceForge is | |
| well documented in the | |
| <a href="http://sourceforge.net/docman/display_doc.php?docid=6445&group_id=1" | |
| >Guide to the File Release System (FRS)</a>.</p> | |
| <p>SFPDE users can use the FRS to publish plug-in jar files. You | |
| should also release your plug-in source as part of each release. | |
| There are several ways to do this: you can include source in your | |
| jar file (to facilitate debugging in Eclipse) or you can use an | |
| Ant task to create a zip file of your source. The fewer the number | |
| of files in a release, the easier it is to manage, so it is best to | |
| minimize files by using archive files (jar files, zip files, tar.gz | |
| files, etc.) to collect the files for a release. Note that with open source projects, users often expect releases to | |
| contain the source. It is considered impolite to force users to fetch the | |
| source from CVS. Do not forget to include your license file in | |
| your release.</p> | |
| <p>To create a release, follow these steps:</p> | |
| <ol> | |
| <li>Login to SourceForge</li> | |
| <li>Select your project</li> | |
| <li>Go to the Admin panel for your project and select the File | |
| Releases link from the navigation menu to enter the FRS.</li> | |
| <li>Define a <em>FRS package</em> if none is defined. | |
| A FRS package a collection of files associated with a | |
| project; each plug-in can map to a FRS package. | |
| For my eclipseexeditor project, the FRS contains one package — | |
| eclipseexeditor — as shown in the | |
| <a href="http://sourceforge.net/project/showfiles.php?group_id=137861" | |
| >Files</a> page .</li> | |
| <li>Use anonymous FTP to upload files to upload.sourceforge.net. | |
| You may use your favorite FTP client for this. SourceForge does | |
| not provide anonymous web upload.</li> | |
| <li>Define a new release — typically named after the version | |
| number, such as 0.1, 1.0Beta2, 1.0, 2.0, etc. — for your package | |
| by using the SourceForge web interface.</li> | |
| <li>Add files from the anonymous FTP site to the release. The | |
| SourceForge web interface provides all you need for this — you | |
| add a new file to the release, select that file from the set of all | |
| files in the upload area and select a file type. Remember that other SourceForge users are | |
| building releases at the same time, so you will see other files | |
| there.</li> | |
| <li>Verify the release contents by downloading and installing the | |
| plug-in in a clean Eclipse installation.</li> | |
| </ol> | |
| <p>To create a new release, simply click the | |
| Add Release button and submit the web form to create a new release. | |
| You can then add the files from the anonymous upload site to the | |
| release.</p> | |
| <div style="text-align: center;"> | |
| <p><img alt="File Release System - Add a Release" | |
| src="images/frs.png" | |
| title="File Release System - Add a Release"/></p> | |
| </div> | |
| <p>SourceForge offers download statistics for each released file. | |
| You can monitor how many people have downloaded your source zip or | |
| Eclipse plug-in. </p> | |
| <p>You may also want to have a look at the <a href="http://sfutils.sourceforge.net">sfutils</a> package. | |
| It provides an Ant task and | |
| Java API to automate software releases on SourceForge. With | |
| sfutils, you can make a release directly from Eclipse by running | |
| Ant.</p> | |
| <h4>Building a web site</h4> | |
| <p>SourceForge provides enhanced web hosting for projects. In | |
| addition to basic HTML services, you get:</p> | |
| <ol> | |
| <li>DNS registration. The URL | |
| <code>http://yourprojectname.sourceforge.net</code> is reserved | |
| for your project web site. For example, my ETEE project is | |
| hosted at <a href="http://eclipseexeditor.sourceforge.net"> | |
| http://eclipseexeditor.sourceforge.net</a>. I emphasize again | |
| the importance of choosing a good project name from the | |
| beginning.</li> | |
| <li><a href="http://php.net/">PHP</a>, | |
| <a href="http://perl.com/">Perl</a>, | |
| <a href="http://python.org/">Python</a> scripting.</li> | |
| <li>MySQL database.</li> | |
| </ol> | |
| <p>You can of course use Eclipse to develop this content. For | |
| example, you may use the Eclipse Web Tools project to create your | |
| HTML content. There are also PHP authoring plug-ins.</p> | |
| <p>To publish your content, you must use SSH secure copy. | |
| You must login under a | |
| project's administrator id, which gives you write access to | |
| the web page space. Due to the large number of hosted projects, | |
| SourceForge uses a branching directory structure to make it | |
| easier to navigate and so that clients do not have to download | |
| extremely large directory listings. For example, my eclipseexeditor | |
| project is stored at | |
| <code>/home/groups/e/ec/eclipseexeditor</code>. I use WinSCP to | |
| copy files from my home computer to the SourceForge server. In this | |
| <a href="images/WinSCP.png">screenshot</a>, I drag a file | |
| from the Eclipse package explorer to WinSCP's folder | |
| representing my SourceForge-hosted project web space.</p> | |
| <p>Each project is required to | |
| <a href="http://sourceforge.net/docs/E07/en/#top">display the | |
| SourceForge logo</a> on their web pages hosted on the project web | |
| service. There are several logos available. You get the logo | |
| image from a special SourceForge URL that includes your project | |
| group id. The SourceForge server records a page hit for your project | |
| when a web browser displays the image. For example, the image URL | |
| <code>http://sourceforge.net/sflogo.php?group_id=137861&type=1</code> | |
| counts as a web hit for my ETEE project with the group id 137861. | |
| Be sure to use the correct logo image URL so your project gets | |
| accurate web statistics.</p> | |
| <h4>Hosting an update site</h4> | |
| <p>You may wonder if you can use the SourceForge web hosting | |
| service to host an Eclipse Plug-in update site. There is little | |
| guidance on this that I know of. Some people report that this is | |
| frowned upon because SourceForge encourages the use of the File | |
| Release System (FRS) for hosting binaries. The FRS uses mirror | |
| sites around the world to support scalable download services for | |
| SourceForge projects. In addition, if you use the FRS, you get the | |
| benefits of download statistics that show download counts. Such | |
| download counts can raise your project's activity rating and | |
| add some momentum to your project. Nevertheless, you have the following | |
| alternative for your update site:</p> | |
| <ul> | |
| <li>If you want to host an update site on your project web site | |
| instead of using the FRS, you should ask the SourceForge | |
| administrators first. It may be bad etiquette to | |
| place binary files on the project web site — if overused, binary | |
| file downloads could affect web page hosting performance for all | |
| SourceForge projects. To deploy your update, you will just need | |
| to copy the site to your project web space.</li> | |
| <li>If you want to host an update site using the FRS, the | |
| procedure is a bit more complex. The FRS uses mirror sites, so | |
| you will need to design your update site so that it obtains files | |
| from one mirror only. In addition, the FRS is a flat structure | |
| with a single directory per project. Therefore any plug-in and feature | |
| you release must have a unique name — you cannot have a feature jar | |
| that has the same name as a plug-in jar. | |
| You then need to make a release for each feature | |
| and plug-in jars to the FRS. Then you need to create an enhanced | |
| site.xml file manually. You can find a good example | |
| <a href="http://eplug.sourceforge.net/site.xml">here</a> with | |
| some explanations at the bottom of the | |
| <a href="http://eplug.sourceforge.net/">eplug project home page</a>, which uses that approach. | |
| With a bit more | |
| work, it should even be possible to take advantage of the Sourceforge mirrors.</li> | |
| </ul> | |
| <p>One additional option to consider is to bundle a full update | |
| site (the <code>site.xml</code> and jar files etc.) into an | |
| archive, and make that file part of your release. Then, users can | |
| download the update site and host it locally, for example on a | |
| local Eclipse update site on a corporate intranet. Since people | |
| will share binaries anyway, you can make it easier and help with | |
| wider adoption of your plug-in.</p> | |
| <p>Since an update site can manage multiple plug-ins versions, you | |
| should consider defining a separate SourceForge FRS | |
| 'package' for your update site archive. If you simply | |
| include the update site (call it <code>update-site.zip</code> ) in | |
| the normal plug-in package, version 1.0 of | |
| <code>update-site.zip</code> will contain version 1.0 of your | |
| plug-in. Version 1.1 of <code>update-site.zip</code> will contain | |
| both 1.0 and 1.1 of your plug-in. Since SourceForge never deletes | |
| previous releases, this practice leads to a lot of unnecessary wasted | |
| server space and potential confusion. I find easier to maintain | |
| only one release of an update site package (with a release name of | |
| "updates" instead of a numbered release name). Then, each | |
| time you release a new version of the plug-in, simply replace the | |
| current <code>update-site.zip</code> — which contains whatever | |
| plug-in versions you wish — within that updated package's | |
| release.</p> | |
| <h4>Registering with a plug-in promotion site</h4> | |
| <p>Once you have your plug-in deployed via SFPDE, you need to tell | |
| the Eclipse community about it. In addition to the SourceForge | |
| Trove, you may wish to consider registering your Plug-in on one of | |
| several plug-in listing sites that you can find on the Eclipse.org | |
| <a href="http://www.eclipse.org/community/pluginsites.php">community | |
| page</a>.</p> | |
| <p>If one of these sites does not drive enough traffic to your | |
| plug-in, you can always write and publish an article about Eclipse | |
| and figure out an interesting way to plug your plug-in in your | |
| article!</p> | |
| <h3>Parting Thoughts</h3> | |
| <p>Explore all the services the '<strong>SourceForge Plug-in | |
| Development Environment</strong>' has to offer. Once you have created, | |
| configured, and populated your project site, refer to your | |
| project's Admin link and the on-line SourceForge documentation | |
| to learn how to:</p> | |
| <ul> | |
| <li>Backup up your configuration</li> | |
| <li>Use the compile farm</li> | |
| <li>Choosing your support options</li> | |
| <li>Creating Mailman mailing lists and hosting web discussion | |
| forums</li> | |
| </ul> | |
| <p>You will find that SourceForge is a tremendous resource for open | |
| source development and the project management of Eclipse plug-ins | |
| development projects — a web hosting equivalent of the Eclipse | |
| desktop experience. | |
| Plug into SourceForge today and see your plug-in reap the myriad | |
| benefits SFPDE — SourceForge + Eclipse PDE — has to offer.</p> | |
| <h3>Resources</h3> | |
| <ul> | |
| <li><a href="http://sourceforge.net/">SourceForge.net</a></li> | |
| <li>SourceForge.net | |
| <a href="http://sourceforge.net/docman/display_doc.php?docid=6048&group_id=1" | |
| >Terms of Use</a></li> | |
| <li><a href="http://sourceforge.net/docs/">SourceForge End User | |
| documentation</a></li> | |
| <li><a href="http://www.opensource.org/">opensource.org</a> (OSI)</li> | |
| <li><a href="http://www.javaforge.com/">JavaForge (a SourceForge alternative)</a></li> | |
| </ul> | |
| <hr style="width: 100%; height: 2px;"/> | |
| <h3>Revision History</h3> | |
| <table border="1" cellpadding="2" cellspacing="2" style="width: 100%; text-align: left;"> | |
| <tbody> | |
| <tr> | |
| <th style="vertical-align: top;">Date</th> | |
| <th style="vertical-align: top;">Comment</th> | |
| </tr> | |
| <tr> | |
| <td | |
| style="vertical-align: top; background-color: rgb(238, 238, 238);"> | |
| October 14, 2005</td> | |
| <td | |
| style="vertical-align: top; background-color: rgb(238, 238, 238);"> | |
| Created; David J. Biesack, | |
| david_biesack@users.sourceforge.net</td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| <p>Copyright © 2005 by David J. Biesack</p> | |
| <p>To discuss or report problems in this article see <a | |
| href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=94940">bug 94940</a>.</p> | |
| <p><small>VA Software and OSTG are trademarks of VA Software | |
| Corporation. SourceForge is a registered trademark of VA Software | |
| Corporation in the United States and other countries.</small></p> | |
| <p><small>Java and all Java-based trademarks and logos are | |
| trademarks or registered trademarks of Sun Microsystems, Inc. in | |
| the United States, other countries, or both.</small></p> | |
| <p /> | |
| </body> | |
| </html> | |