Contributing to OpenOffice.org

Last updated 2003-02-16

Preface

"Contributing" to OpenOffice.org in a developer role, as opposed to participation via the mailing lists, takes the form of posting either information or code to the appropriate project area of the site. In all cases, the requirments for doing this are:

• Joining OpenOffice.org to establish a userid with the site.
• Submit the Joint Copyright Assignment
• Obtain a cvs client for the platform you are using.
  Code or information contributions involve using the Common Versioning System (CVS). Contributors will need some basic familiarity (in most cases) with this utility to post information to the site. More information follows in the cvs section
• Obtain an ssh client for the platform you are using.
  OpenOffice.org cvs is implemented through ssh "tunneling" (port forwarding). Therefore, in addition to a cvs client appropriate for the platform you are using, you will also need an ssh client. Additional information about can be found in the ssh information section.

The Joint Copyright Agreement

We ask that all code submitted to OpenOffice.org be submitted via IssueZilla. In your submission please list "Issue Type" as PATCH. Your code will be sent to the committer for the appropriate project.

1. Submit a filled-out copy of the Joint Copyright Assignment form (JCA); we have a PDF version you may print out. We explain our reasons for requiring the JCA in the Licensing FAQ. The FAQ further explain the use and advantages of using this license.
   
2. In order for your code to be committed to the source tree:
   1. Your Joint Copyright Assignment form must have been received. This Assignment covers all submissions of code.
   2. The committer must approve your code for submission.

OpenOffice.org maintains a list of persons and companies who have filed a copyright assignment (JCA or the previous Copyright Assignment). If you have filed either the JCA or the previous Copyright Assignment form and your name is not on the list, please contact the Webmaster.

CVS

The Concurrent Versions System (CVS) is a version control system for keeping track of all modifications to project source code files. CVS is widely used in both open source and proprietary software development projects, and is generally considered to be the best freely available, full-featured version control tool. Two special features make CVS particularly suited to collaborative development across the Internet:

1. CVS allows multiple developers to edit their own working copies of files simultaneously, then deals with combining all the changes and notifying developers when there are conflicts.
2. Remote access to source code file repositories. Developers who are project members can obtain and modify project files from virtually anywhere.

CVS has existed for many years primarily on UNIX systems to aid in application development where many programmers may be involved. More recently, it is used as a means to provide versioning control for a variety of information stored in a central repository where many contirbutors are involved--like OpenOffice.org! A good introduction to CVS can be found in Introduction to CVS at the CVS home site. Another good resource on using CVS is the Day With CVS book.

CVS is a client-server system. The CVS repository is maintained on a central server; clients run on users' machines and connect to the server via the Internet. Clients connect using one of several cvs access methods, typically to the default port of 2401 on the server machine. Typically if you have an actual login account to the machine where the cvs repository resides, you would make cvs connections by directly referencing, or connecting to, the repository. However, OpenOffice.org doesn't allow for direct accounts on the server. Hence, you will be using a method called ssh tunneling in order to make CVS connections. More about how this is done in the ssh section. CVS has many options and commands, but the main ones for getting and putting back code are checkout and commit. The connect repository string for OpenOffice.org is:

-d:pserver:"userid"@localhost:/cvs

A complete cvs command for checking out the cvs tree from the website project area would be:

cvs -z3 -d:pserver:"userid"@localhost:/cvs checkout website

for a command line implementation of cvs. (More about what's actually going on here in the next section.) This command would extract the complete cvs tree of the "website" project and put in in a local directory(folder) called "website". What you actually do will depend on the client you have installed.

In order to participate as a developer in OpenOffice.org, you will need some basic familiarity with cvs and a cvs client or application installed on your development machine. Two good sources for cvs clients for Windows and Mac users are the winCVS site and the Thornleyware CVS client listing site. Unix developers can get the source for cvs directly from the cvshome site. Linux developers can ususally obtain command line cvs and other GUIs for cvs from their distribution source.

SSH

SSH, secure shell, is a means of connecting to or logging on to a server using an encrypted connection. There are a variety of encryption mechanisms that can be used for this purpose. In order to gain developer access to OpenOffice.org and use cvs to checkout and upload changes, you will also need an ssh client and an addtional utility called ssh-keygen (or its equivalent) in order to gain access to the site.

Good resources for ssh clients for various platforms can be found at:

• www.freshssh.org
• www.openssh.org

You'll need to generate a key type of "dsa/ssh2" in order to connect to OpenOffice.org. ssh-keygen generates a private and public part of your ssh key. The private part is normally stored in a file called "id_dsa" in the ssh directory on your system, and the public part is stored in "something".pub. On Unix systems, the ssh directory is called .ssh but this may vary with your particular setup.

Once your ssh keys are generated, you'll need to submit the public portion of your ssh key pair to OpenOffice.org via Issuezilla. File an issue and attach the public key to the issue. Assign it to ssh2key@openoffice.org in the "www" component. You will receive notification when you have been given access. You should have previously joined OpenOffice.org in some capacity and have an existing userid in place.

Additional information concerning cvs and ssh issues for some implementations can be found in the OpenOffice.org SSH Guide

Using SSH for Tunneling

As previously mentioned, ssh tunneling is the means used to actually make a connection to OpenOffice.org to then use cvs to extract and update files to which you have been access.

Once your ssh public key has been added to the OpenOffice.org ssh database and is usable, you basically need to open an ssh session as follows (assuming command line ssh--your GUI ssh implementation may provide alternate means for accomplishing the same thing):

ssh -2 -x -L 2401:localhost:2401 tunnel@openoffice.org

basically this means to use ssh protocol "2", disable X forwarding (only applicable to Unix users using X windows), re-route the server port 2401, the default cvs connection port to your local machine, and use "tunnel@openoffice.org" as the host connectivity string to this session.

Another option that may come into play is the "-i" option to identify the actual name of your private key file if it isn't the default of "id_dsa". It's fairly critical to connectivity to have your public key file identified correctly.

Connecting with the ssh tunnel will leave you in basically a suspended mode with your ssh application. Once you've established connectibvity, however, you will be able to use your cvs application to transfer files.

 

Thank you for your participation in OpenOffice.org. We look forward to your contribution! If you have any questions, please contact us.