Atom: http://mail-archives.apache.org/mod_mbox/www-community/?format=atom
"community@apache.org feed"
Title: Contributors Tech Guide
Notice: Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
.
http://www.apache.org/licenses/LICENSE-2.0
.
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
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](../foundation/contributing.html) for
other ways to contribute (i.e. donations).
If you have commit access to a repository, please also read the [Committers
FAQ](committers).
# Contents #
[TOC]
# How Open Source Works # {#howitworks}
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](http://www.apache.org/) , the [ASF How it
works](../foundation/how-it-works.html) document, the [Apache Jakarta:
Understanding
Opensource](http://jakarta.apache.org/site/understandingopensource.html)
document, the [FSF website](http://www.opensource.org/) , the [Open Source
Initiative Website](http://www.opensource.org/) , the [The Cathedral and the
Bazaar](http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/)
paper and [Google](http://www.google.com/).
# Getting the sources from the Subversion repository # {#svnbasics}
Subversion (SVN), is the version control system used at Apache. See [The
Subversion Homepage](http://subversion.apache.org/) for more about SVN.
## Bleeding-edge ## {#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 it's 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](http://www.apache.org/dyn/closer.cgi/) 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 by
[Apache](http://subversion.apache.org/). You will find most tools noted
here on this site or related sites at [Tigris](http://tigris.org) the
previous home of Subversion. 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](http://svnbook.red-bean.com/).
Under Windows, there are a few options for you:
## Use cygwin ## {#svn-cygwin}
[Cygwin](http://www.cygwin.com/) 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 ## {#svn-cli}
The Subversion utilities are available as native Windows binaries. Get them
from [the Subversion homepage](http://subversion.apache.org). To use these
tools, open a command window (click Start > Run..., then type 'cmd'),
then enter the following commands:
(Note: 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 SVN utility to your PATH.)
mkdir C:\checkout
cd /D 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](http://ant.apache.org/) , 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 authentication and allows you to
commit your changes.
## Use TortoiseSVN ## {#svn-tortoise}
[TortoiseSVN](http://tortoisesvn.tigris.org/) 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...` :
![screenshot of SVN checkout](images/tortoisesvn-checkout.jpg "screenshot
of SVN checkout")
Then, fill out the settings like in the screenshot below, and then click
ok.
![screenshot of SVN settings](images/tortoisesvn-settings.jpg "screenshot
of SVN settings")
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 ## {#svn-nix-cli}
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 ## {#svn-ide}
Most decent IDEs these days provide Subversion integration. See the [IDE
Developer's Guide](http://jakarta.apache.org/site/idedevelopers.html) 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:
| IDE | Plugin/Extension |
|-----|------------------|
| [Eclipse](http://www.eclipse.org) | [Subclipse](ext:tigris/subclipse) |
| [JetBrains IDEA before version 5](http://www.jetbrains.com/idea) | [svn-up](http://svnup.tigris.org) |
| [NetBeans](http://www.netbeans.org) | [Subversion profile](http://vcsgeneric.netbeans.org/profiles/index.html) |
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 ## {#svn-update}
You don't need to check out a entire module every time 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
# Providing feedback # {#providingfeedback}
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](http://www.dtcc.edu/cs/rfc1855.html#3) 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 enthusiastic 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...
# Sending in a Bug Report # {#bugreports}
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](http://issues.apache.org/bugzilla/enter_bug.cgi), or [Jira](http://issues.apache.org/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.
# Sending in Patches # {#patches}
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 SVN (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 SVN 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 '>' redirection 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](https://issues.apache.org/bugzilla/) or
[Jira](https://issues.apache.org/jira/) depending on the project. If a bug report
doesn't exist yet, create one. A very few 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. If the patch is large, please ask before e-mailing it
in case there is a better way to provide it.
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 any feedback in a reasonable amount of time (say a week or two),
feel free to send a follow-up e-mail to the developer list. Open Source developers are all
volunteers, often doing the development in their spare time.