This document is targetted at Apache contributors. A contributor is
any individual who wants to contribute to the projects hosted by the Apache
Software Foundation (ASF). If you are not a contributor and not interested in
becoming one, this page is not for you.
This document is about the technical means you can use to contribute.
See the ASF Foundation
contribution page for other ways to contribute (i.e. donations).
If you have commit access to a repository, please also read the
Committers FAQ.
Contents
Several books and many papers have been written about the way open
source works and how you become a valuable member of the open
source/free software community. This document isn't one. Try the
ASF front page, the
ASF How it works document, the
Apache Jakarta: Understanding Opensource document, the
FSF website, the
Open Source Initiative Website,
the The Cathedral and the Bazaar paper and
Google.
Subversion (SVN), is the version control system used at Apache. See The Subversion Homepage for more
about SVN.
Bleeding-edge
Getting the source directly from the source repository usually gives
you the bleeding edge version of that particular project. To be more precise,
in the Subversion repository, there are usually three separate top-level
directories: trunk, tags and branches.
The trunk directory contains the current source code, and thus
its usually used in the source code access urls given by the projects.
The tags directory contains specific versions of the project that
were tagged with some name. These were created for some specific reason. For
instance, you usually find a tag for each released version of the project.
The branches directory finally contains versions of the project that are
different in some respect, such as experimental versions, or former released
versions.
So, in short, if you are looking to download the source code for stable
versions of the ASF projects, you should go to a normal mirror site and simply
download it from there. Only if you want the bleeding edge source (from the
trunk folder, or if you need an older version for which you
don't get the source code from the mirrors anymore, use the source repository.
Before you start using source code from the source repository, you need to check
out a local copy of the remote repository. Here's how.
Subversion, which is the technology/tool used by Apache to maintain the source
repository, is an open source project hosted at
Tigris. You will find most tools noted
here on this site or related sites at Tigris. So, if your system is not listed here,
please go to Tigris and see what options are available to you.
Also, if you want info about Subversion, you'll find it for instance in the
Subversion book.
Under Windows, there's a few options for you:
Use cygwin
Cygwin is a free
software suite of ports of popular Linux tools and utilities
to run natively under windows. Among it is a port of the svn
application which is the Subversion client required for checking out
source code from the Apache source repositories.
If you use cygwin, please follow the Unix/Linux instructions below.
Use the command-line tools
The Subversion utilities are available as native Windows
binaries. Get them from the Subversion homepage. To use
these tools, open a command window (click Start > Run...,
then type 'cmd'), then enter the following commands:
rem you can use any directory in place ^
of C:\checkout. replace %SVNUTILS% with ^
where you installed the svn binary, e.g. with, ^
C:\svn-win32-1.3.2\bin, ^
or with nothing if you added the ^
utility to your PATH
mkdir C:\checkout
cd C:\checkout
%SVNUTILS%\svn.exe svn checkout http://svn.apache.org/repos/asf/infrastructure/site/trunk/ site
This will checkout the ASF website into a sub-directory called
site. The checkout will take a while, depending on your connection.
Go ahead and grab yourself a coffee or ten. When done, you
should have checked out the sources for the website you're
reading now (unfortunately it won't suffice for actually
re-creating it, you'll also need Apache Ant, which you
should go install right now if you haven't already).
Yes, you can enter these URLs into a browser and actually
look at the sources before checking out anything. However, for
this you should probably use the Web view at
http://svn.apache.org/viewvc/ as it is much nicer
to use than the raw view.
The above URL gives you read-only access. If you're a committer,
then you should use instead
svn checkout --username [username] https://.... The https
access requires authentification and allows you to commit your changes.
Use TortoiseSVN
TortoiseSVN is
a neat extension for the Windows Explorer which integrates
SVN. Using it is real simple:
After you've created a folder where you want to check out
the sources to, right-click and select
SVN Checkout...:
Then, fill out the settings like in the screenshot below,
and then click ok.
This checks out the source of the site that you're looking at.
Under Unix/Linux, there are multiple options, too:
Use the command-line tools
The Subversion utilities are available as native Unix and
Linux binaries. Chances are you already have them installed.
Try it by opening a console and typing 'svn'. If you get an
error along the lines of "bash: svn: command not found", then
you need to install them first. How you do that, depends on
what Unix or Linux you have. For instance, with Debian or
Ubuntu, you can do so by opening a console window and entering the
commands:
su -
# enter the root password when prompted
apt-get update
apt-get install svn
exit
Other systems have graphical installers or use the rpm tool.
Please refer to the documentation of your system for
instructions on how to install software
Once you have these tools installed, open a command window,
then enter the following commands:
# you can use any directory in place of ~/checkout
mkdir ~/checkout
cd ~/checkout
svn checkout http://svn.apache.org/repos/asf/infrastructure/site/trunk/ site
This will checkout this very documentation that you're
reading, into a sub-directory called site. Note that depending
on your connection this will take a while.
Using an IDE for source repository access
Most decent IDEs these days provide Subversion integration. See the
IDE
Developer's Guide if you need information on how to
configure your IDE (note this is a java-centric paper).
For Java IDEs, you might have to install a plugin in order
to get SVN support:
Please refer to the documentation of the IDE and the plugin/extension for how to install
and use the plugin/extension.
Updating your checked-out module
You don't need to check out a entire module evertime
something is changed. To synchronize your local copy with the
remote repository, you use the svn update which
goes like this:
# location where the module is stored
cd checkout
# either you call the update in the module's directory
# or you supply the list of modules to update, like this
svn update site
With graphical clients, the process is similar. For example,
in TortoiseSVN you can right-click on any subversion checkout
directory, and select the "SVN Update" option
A valuable way to contribute to ASF projects is by using the
software, and then providing feedback about them to its developers.
Different software projects have different preferences about how you
should go around to submitting feedback. Check out the project
website for more information. In absence of information on how to
provide feedback on a project's website, follow these
guidelines.
A vital part of the ASF projects are the project mailing lists.
Most have a users list named users@${project}.apache.org. Subscribe
to it by sending an e-mail to users-subscribe@${project}.apache.org,
then follow the instructions. Be sure to follow netiquette and be
nice to the developers.
Then, tell the developer and user community about your use of the
software product, your experiences in setting it up, issues you
encountered, stuff like that. Your story will likely be very welcome
if well-written and you Read The Manual before doing anything silly,
and you'll probably receive some enthousiastic response from some of
the developers and other users (if not, don't worry. They're
probably just busy with other things). If you found specific issues
or have a specific idea about how things should work, you'll likely
be asked to submit a bug report or patch to improve things :D...
We take bugs very seriously. To help us to quickly fix the bug,
be sure to include as much information with your report as possible
such as your platform, version numbers, error logs, configuration,
etc. When you are not sure whether a piece of information is
relevant, include it.
To submit a bug report, first make sure the bug hasn't been
reported before, fixed in a newer version of the software, or fixed
in the current development version. Then file a report. Different
projects have different preferences for this. Usually you are asked
to enter the bug into a bug tracking database, which is normally
either Bugzilla,
Scarab or Jira. Some projects don't
use an issue tracker. In that case, send the bug report to the
appropriate mailing list.
If you have the knowledge to supply a patch that fixes the issue,
please do so...
Note most issue trackers also support placing requests for
enhancements in the database. Feel free to do so. Make sure to set
the appropriate flags in the issue tracker to indicate that your
request is not about a bug.
When your bug report is not addressed, try and submit a patch for
it. It'll increase the chances of the bug getting fixed.
A patch is a computer-generated file that describes differences
between different versions of one or more sourcefiles. Once again,
different software projects have different preferences about how you
should go around to submitting patches. Check out the project
website for more information. In absence of information on how to
provide feedback on a project's website, follow these
guidelines.
Patches are generated using the unix utility diff or
the svn diff command. They can be applied using the
unix utility patch. When you want to contribute a
change or addition to existing sourcecode, you should:
- check out the latest copy of the sources from cvs (see above)
- change the sourcefiles to incorporate your change or
addition. Make sure you also provide appropriate source code
documentation (like javadoc for java sources), and follow a project's
coding conventions.
- check the software still compiles and runs correctly
- run any unit or regression tests the software may have
If this works, you can create your patch. Remove all build
products and remnants from the module tree (like any 'build', 'dist'
or 'bin' directories), then build the actual patch. Here's how to do
it using the commandline cvs client under unix:
Apache projects prefer the unified diff format. The subversion
tool creates that automatically. If you use other tools, please
refer to their documentation for details on set the diff format.
# location where the modules are stored
cd checkout
# directory of the module
cd site
# creation of the diff
svn diff > site.patch
The Subversion client now examines all subdirectories for changed files,
then compares the changed file to the one on the server. It
generates the patch. The '>' pipe results in the resulting patch
being put in a textfile named (in this case) site.patch.
With your patch generated, you need to send it to the developers.
Different projects have different preferences for this. Usually you
are asked to add it as an attachment to the relevant bug report in
the bug tracking database, which is normally either Bugzilla or Jira depending on the project.
If a bug report doesn't exist yet, create one. Some projects don't
use an issue tracker. In that case, send the patch as an attachment to
an e-mail with a subject prefixed with "[PATCH]". Patches should be sent to
the appropriate development mailing list.
You should supply a patch-per-issue, that is, a patch can span
multiple files but you should normally try not to fix multiple bugs
in a single patch, unless those bugs are intimately related.
Please show some patience with the developers if your patch is
not applied as fast as you'd like or a developer asks you to make
changes to the patch. If you do not receive feedback in a reasonable
amount of time (say a week), feel free to resubmit your patch. Open
Source developers are all volunteers, often doing the development in
their spare time.