content/tools/dev_docs/howtocontribute.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<head>
	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
	<TITLE></TITLE>
	<META NAME="GENERATOR" CONTENT="StarOffice 7  (Linux)">
	<META NAME="CREATED" CONTENT="20031015;15235100">
	<META NAME="CHANGED" CONTENT="20031022;335100">
	<STYLE>
	<!--
		@page { size: 8.27in 11.69in; margin: 0.79in }
		P { margin-bottom: 0.08in }
		H1 { margin-bottom: 0.08in }
		H1.western { font-family: "Arial", sans-serif; font-size: 16pt }
		H1.cjk { font-family: "Lucida Sans Unicode"; font-size: 16pt }
		H1.ctl { font-family: "Tahoma"; font-size: 16pt }
		H2 { margin-bottom: 0.08in }
		H2.western { font-family: "Arial", sans-serif; font-size: 14pt; font-style: italic }
		H2.cjk { font-family: "Lucida Sans Unicode"; font-size: 14pt; font-style: italic }
		H2.ctl { font-family: "Tahoma"; font-size: 14pt; font-style: italic }
		H3 { margin-bottom: 0.08in }
		H3.western { font-family: "Arial", sans-serif }
		H3.cjk { font-family: "Lucida Sans Unicode" }
		H3.ctl { font-family: "Tahoma" }
		H4 { margin-bottom: 0.08in }
		H4.western { font-family: "Arial", sans-serif; font-size: 11pt; font-style: italic }
		H4.cjk { font-family: "Lucida Sans Unicode"; font-size: 11pt; font-style: italic }
		H4.ctl { font-family: "Tahoma"; font-size: 11pt; font-style: italic }
		H5 { margin-bottom: 0.08in }
		H5.western { font-family: "Arial", sans-serif; font-size: 11pt }
		H5.cjk { font-family: "Lucida Sans Unicode"; font-size: 11pt }
		H5.ctl { font-family: "Tahoma"; font-size: 11pt }
		H6 { margin-bottom: 0.08in }
		H6.western { font-family: "Arial", sans-serif; font-size: 10pt }
		H6.cjk { font-family: "Lucida Sans Unicode"; font-size: 10pt }
		H6.ctl { font-family: "Tahoma"; font-size: 10pt }
	-->
	</STYLE>
</head>
<body LANG="en-US" DIR="LTR">
	
	
<div style="padding:3pt; background-color: #f8d3d0; margin-top: 4pt; margin-bottom: 4pt;">
<h2>Warning</h2>
<p>Much of the information here is <b>outdated</b> and refers to obsolete project procedures.</p>
<p>For current information on how to contribute to OpenOffice, see 
   <a href="http://openoffice.apache.org/get-involved.html">this page</a></p>
</div>
	
	
	
	
<H1 CLASS="western">How to contribute to OpenOffice.org</H1>
<P>(Draft 0.1 2003/10/31 please provide feedback to mh at
openoffice.org)</P>
<P>This document describes different possibilities about how to
contribute to (or participate in) the OpenOffice.org project. I
assume that you are already a user of OpenOffice.org and want to take
the first steps of being more than just a user.</P>
<H2 CLASS="western">Roles in OpenOffice.org Project</H2>
<H3 CLASS="western">OpenOffice.org User</H3>
<P>You may have question about the usage of OpenOffice.org? You even
may have answers for other users questions? Subscribe to
<A HREF="mailto:users@openoffice.apache.org">users@openoffice.apache.org</A> and
help by answering questions.
You can also contribute templates and documentation to
the documentation project for other users to make use of.</P>
<H3 CLASS="western">OpenOffice.org Macro Programmer, Plug-in or Addon
Developer</H3>
<P>In this role you are probably most interested in developing you
own code using the interfaces provided by OpenOffice. These
interfaces are called UNO APIs and you can get documentation from the
<A HREF="http://api.openoffice.org/">http://api.openoffice.org</A>
project and help from the <A HREF="mailto:dev@api.openoffice.org">dev@api.openoffice.org</A>
list.</P>
<H3 CLASS="western">OpenOffice.org Power User</H3>
<P>If you already know about internals of OOo you may subscribe to the
different dev@*.openoffice.org lists. Here you are able to discuss
with the developers about problems and enhancements. You also can use
IssueZilla, the OpenOffice.org Bug Tracking System to file your
problems or feature requests into the Database. (see also
ircs://irc.libera.chat/openoffice for on line discussions)</P>
<H3 CLASS="western">OpenOffice.org Quality Assurance</H3>
<P>If you are interested on being on the bleeding edge it might be
useful to join the QA Team (<A HREF="mailto:qa@openoffice.apache.org">qa@openoffice.apache.org</A>).
There are several interesting projects like automatic GUI testing
(<A HREF="http://qa.openoffice.org/qatesttool">http://qa.openoffice.org/qatesttool</A>)
and OOo API testing (<A HREF="http://qa.openoffice.org/qadevOOo">http://qa.openoffice.org/qadevOOo</A>)
as well as the daily QA work (see also
ircs://irc.libera.chat/openoffice )</P>
<H3 CLASS="western">OpenOffice.org Content Developer</H3>
<P>In the OpenOffice.org Project there are not only things to do
directly related to the Product but there is also a lot of other work
left in the OpenOffice.org project. If you want to enhance any of the
OOo web pages, you need status of a content developer. Ask your
project lead for this role. You are encouraged to sign an JCA, but as
long we have the common understanding that the contribution to any
web content is treated as Public Domain, this is not mandatory.</P>
<H4 CLASS="western">Native Lang Projects</H4>
<P>There are several Native-Lang projects on OpenOffice.org which you
can join. These projects offer users information about OpenOffice.org
in their native languages. This makes OpenOffice.org more open to non
English speaking people.</P>
<H4 CLASS="western">Established Projects</H4>
<P>Also the already established long existing projects are looking
for helpers to extend project documentation. 
</P>
<H4 CLASS="western">Marketing Project</H4>
<H4 CLASS="western">Incubator Projects</H4>
<P>Bibliographic, WordPerfect filter, Groupware, etc. All of these
are in need of developers to contribute and because they use only the
OpenOffice UNO APIs, it should be easier for a developer wanting to
get their hands on code to develop and contribute.</P>
<H3 CLASS="western">OpenOffice.org Developer</H3>
<P>You may even have patches attached to issues, new implementations for the
OpenOffice.org code base. Participate on the projects dev lists and
you may achieve developer status quickly. This includes the content
developer status.</P>
<H4 CLASS="western">OpenOffice.org Porting</H4>
<P>You want to port OpenOffice.org to a new platform ? Look on
<A HREF="mailto:dev@porting.openoffice.org">dev@porting.openoffice.org</A>
for other interested people.</P>
<H4 CLASS="western">OpenOffice.org Localizations</H4>
<P>See <A HREF="mailto:L10N@openoffice.apache.org">L10N@openoffice.apache.org</A>
and <A HREF="http://l10n.openoffice.org/adding_language.html">http://l10n.openoffice.org/adding_language.html</A>
for more info regarding all questions around this topic.</P>
<H3 CLASS="western">Miscellaneous</H3>
<UL>
	<LI><P>Team OpenOffice.org (<a href="www.teamopenoffice.de"> www.teamopenoffice.de</a> *German*)</P>
	<LI><P>Ximian (<a href="http://ooo.ximian.com"> ooo.ximian.com</a>)</P>
	<LI><P>NeoOffice (<A HREF="http://www.neooffice.org/">www.neooffice.org</A>)
	<!-- ---- 10/21/2003, 13:18 ----
I don't know if it is a good idea to advertise forks in the document that describes how to contribute to *our* project. --></P>
	<LI><P>ooodocs www.ooodocs.org</P>
</UL>
<P><BR><BR>
</P>
<H2 CLASS="western">Setting Expectations</H2>
<P>An Office Suite does have many users who have a lot ideas on how to
extend the product or have problems with this product. There
are only a few developers which are able to understand these requests
and are able to implement a solution for it. So for every enhancement
or bug fix we have to find somebody who is able and willing to do so.
At the time of writing there are about 3000 issues which being are worked on
for the next version of OpenOffice.org. This work is done by about
120 developers from which the major part is employed by Sun
Microsystems. We expect that during the life cycle of the next
version about 15000 issues get raised and fixed. And there will be many
more issues which can not be addressed in time for the next version.
Due to the complexity and size of the OpenOffice.org product it is
not possible to wait until all known issues are fixed. We have to find
the balance between &ldquo;the product that contains long awaited
features&rdquo; and all &ldquo;severe bugs&rdquo; are gone.</P>
<P>For this reason we introduced the term &ldquo;Target Milestone&rdquo;
to be able to set an expectation about what version  issues are scheduled to get
fixed. It is common understanding that &ldquo;severe issue&rdquo; has
to be fixed by the next version. Minor issue will get fixed, if
resources for fixing them are allocable or fixes are already
available (see
<A HREF="http://tools.openoffice.org/release/TargetMilestone.html">http://tools.openoffice.org/release/TargetMilestone.html</A>).</P>
<P>It's quite important to understand these resource constraints,
just asking or voting on an issue will not necessarily ensure that an
the issue will get fixed. If there is any different interpretation
about targeting of issues every party has to argue why this is an issue
should been worked on as soon as possible, over other equally important issues.
If it is not possible to
get agreement on this issue it should be raised to the relevant team
lead(s) or the <A HREF="mailto:releases@openoffice.org">releases@openoffice.org</A>
team.  As a last resort, if agreement cannot be achieved it should then be
raised with the Community Council to resolve the issue.</P>
<P><BR><BR>
</P>
<H2 CLASS="western">Development Process</H2>
<P>There are some simple rules to follow for the development process:
<H3 CLASS="western">Master WorkSpaces (mws)</H3>
Builds are done on code lines, which are actually branches
in  cvs repository. These branches are called master branches and for
each code line there is a separate branch. Currently we have
this situation:</P>
<P ALIGN=CENTER>1.1 code line = mws_srx645, 2.0 code line = HEAD</P>
<P ALIGN=LEFT>Once the 2.0 code line has been closed before delivery, the 2.0
code line will also move to a branch (e.g. mws_src680, and
development of following release (3.0 ??) will then happen on CVS
HEAD.</P>
<P ALIGN=LEFT>Contributions to these code lines have to have their
corresponding issues in IssueZilla and will not generally be made 
directly to those branches, but on sub branches called child
workspaces (cws).</P>
<H3 CLASS="western">Child Workspaces (cws)</H3>
<P>Having child workspaces means it is possible to
review and test all changes before they get applied on the master
branch. This have several advantages but also constraints:</P>
<UL>
	<LI><P>Less regressions on the master branch</P>
	<UL>
		<LI><P>We should be able to do a release at production quality from
		the master branch.</P>
		<LI><P>The HEAD of the branch is always consistent and buildable.</P>
	</UL>
	<LI><P>Before reintegration into the master, the cws has to QA'd.
	Without QA approval there is no reintegration.</P>
	<LI><P>Liberal access rights and 'lazy commits' on cws branches.</P>
	<UL>
		<LI><P>Since a commit to cws will not influence the master before
		reintegration, we are able to grant commit access more liberally
		since review is easier and QA is mandatory.</P>
		<LI><P>We can grant commit access to any third parties in a very
		free way, reducing the hurdle for getting patches in. Patches are
		reviewed and QAed on
		the cws before reintegration. This mean cws can be treated as play
		ground for developers and vendors.</P>
		<LI><P>If a cws gets applied to a master branch, Release
		Engineering ensure that it is applied also on the following
		product master branch.</P>
	</UL>
</UL>
<P>A cws does not necessarily have every module tagged with the cws branch tag.
In most
cases only needed modules are tagged with cws branch tag, remaining
modules have to be taken from the master branch (as long as no
changes are needed). There are also cws, where all modules have been
tagged to be on the cws branch, this makes life for casual contributor
easier, they don't have to take care that the module is already
available for the specific cws.</P>
<P>Any implementation of a feature will happen on a separate cws,
this ensures that no incomplete or only partly tested feature will
get into the master. Please avoid implementing more than one big or a few
minor features on one cws. Also don't group too many bug fixes in one
cws to avoid dependencies.  A cws should be shortlived if possible to avoid
divergence from the master.</P>
<H3 CLASS="western">How to get your code contribution to
OpenOffice.org</H3>
<H5 CLASS="western">Issue handling</H5>
<P>If you are going to make your first contribution to the code basis
you have to be familiar with bug handling in IssueZilla. File an
Issue with a good description of what you want to achieve. Make sure
that you got the correct target milestone and the correct owner
assigned. The owner should be always the one, from whom the next
action is expected.</P>
<H6 CLASS="western">Confirmed/Unconfirmed status</H6>
<P>As default issue will be submitted as unconfirmed. The first step
is to get the issue confirmed by a QA or Project member. QA members
will scan unconfirmed issues, if this takes too long, you should ask
for confirmation on the projects dev list. Once the team recognises
the valuable issue submissions you will be granted &ldquo;can confirm&rdquo;
status or simply ask the project lead for this. Developers often
ignores issues with unconfirmed status or will treat them with lower
priority.</P>
<H6 CLASS="western">Target Milestone</H6>
<P>By default issues will have no target milestone. Target milestones
will be set by qa team or developers. If there are different opinions
about target milestone these should solved by the project lead or
<A HREF="mailto:releases@openoffice.org">releases@openoffice.org</A>.
</P>
<H6 CLASS="western">Component/Owner</H6>
<P>Dependent on the selected component (and subcomponent) the issue
will be assigned to an default owner. Don't be afraid to select the
wrong component, the issues will get reassigned after a while to
the correct owner. If you are unsure about which component to use,
you should only
choose among: Chart, Database Access, Drawing, Formula
Editor, Installation, Presentation, Spreadsheet and Word processor.</P>
<H6 CLASS="western">Nothing happens ?</H6>
<P>If nothing happens to your issue after a while, don't hesitate to
ask the current owner directly on the dev list about the status. If
you don't get reaction, ask once more. Also if you get some
insufficient feedback like &ldquo;worksforme&rdquo;, &ldquo;cantreproduce&rdquo;
don't hesitate to ask once more if you think this might not be
correct.  Please provide a reason why you think it is important.</P>
<H6 CLASS="western">Patches</H6>
<P>Code contribution can be attached to an issue. If this
contribution is of significant size (i.e. &gt;= 10 line of code) you
need to sign a JCA before submitting
(<A HREF="http://www.openoffice.org/contributing.html">http://www.openoffice.org/contributing.html</A>).
Your name will be listed on the web page it will last 1 &ndash;
2 weeks :( .</P>
<H6 CLASS="western">committing patches to cvs</H6>
<P>Once you have been recognised as valuable patch contributor, you
will get granted commit access to cvs. Then you will be able after
set up a cvs ssh tunnel to commit patches directly to a cws. But
every commit to cvs has to be accompanied with an issue number, so
that every patch which is going into OpenOffice.org is documented by
an issue. Ask your project lead or <A HREF="mailto:releases@openoffice.org">releases@openoffice.org</A>
to get cvs commit access.</P>
<H6 CLASS="western">Creating a cws</H6>
<P>Unfortunately we are not able to create a cws by our own,
<a href="http://tools.openoffice.org/dev_docs/OOo_cws.html">yet</a>.
We have to ask Sun employees to create them for us Ask the project lead or
<A HREF="mailto:releases@openoffice.org">releases@openoffice.org</A>
for creation of a cws. Important data for creating these is the
expected life time, the targeted code line and who will be
responsible person which will give the ok for passed QA. A
descriptions of the purpose of the cws is also helpful. Creating a
full blown cws (where all modules get tagged within a cws branch tag ) will last
up to two days.</P>
<H6 CLASS="western">Working on a cws</H6>
<P>Do whatever you want there. It's your cws. You may want to use
Bonsai (<A HREF="http://ooo.ximian.com/bonsai">http://ooo.ximian.com/bonsai</A>)
to track any changes on the cws.</P>
<p>It is also possible to set up a tinderbox which multiple build and verify
the cws is buildable on many platforms.</p>
<H6 CLASS="western">Resyncing a cws</H6>
<P>With the longer lifetime of a cws, conflict risks for
reintegration of the cws will also grow. For this reason a resync of the
cws to a newer version of the master workspace (mws) is possible. At
this time this also can be done by Sunnies. Ask for help to do the resync
for you.
</P>
<H6 CLASS="western">QA of a cws</H6>
<P>The minimum QA of a cws is that all issues which have been fixed
on this cws, have been verified by your peers. If features got
implemented, a test plan also should be available. Mandatory is the
successful pass of the smoketest_oo module and the verification on at
least two platforms (Windows and one Unix derivate is a good choice).
A clean and build of is always a good idea, see tinderbox <a href="http://ooo.ximian.com">
for permanent builds.</a> on specific branches.</P>
<H6 CLASS="western">Reintegration into master workspace</H6>
<P>Reintegration of a cws into the master workspace will done by
Hamburg Release Engineering. They will be delighted by every cvs
conflict and build error :). Please try to avoid them and you will get new
friends for life.</P>
</body>
</HTML>