blob: f3677e2ec490b4a02c3071e03378d55a9fad25d3 [file] [log] [blame]
<?xml version="1.0"?>
<!--
Copyright 1999-2006 The Apache Software Foundation
Licensed 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.
-->
<!--
// ======================================================================== 78
-->
<faqs title="How to Help FAQ">
<part>
<p align="center">
"You can't always get what you want /
<br/>
but if you try real hard /
<br/>
you might just find /
<br/>
that you get what you need".
<br/>
[Rolling Stones]
</p>
</part>
<part>
<faq id="involved">
<question>Getting Involved</question>
<answer>
<p>
Every volunteer project obtains its strength
from the people involved in it.
We invite you to participate as much or as little as you
choose.
The roles and responsibilities that people can assume in
the project
are based on merit.
Everybody's input matters!
</p>
<p>
Here is one developer's advice how to get involved.
It specifically talks about Tomcat,
but the general idea can applied to any of the Apache
Projects.
</p>
<ul>
<li>
<a href="http://jakarta.apache.org/site/contributing.html">
Contributing</a>
-- Craig R. McClanahan
</li>
</ul>
<p>
Here is another comment that was sent to the Jakarta
Turbine Mailing
List about the open source process and the contrast
between how an
opensource product and a proprietary product improve
through the user
community.
</p>
<ul>
<li>
<a href="http://jakarta.apache.org/site/understandingopensource.html">
Understanding Opensource</a>
-- Cameron Riley
</li>
</ul>
<p>
While written for ASF developers,
the Rules for Revolutionaries provides insight into how
the
collaborative process works,
and how our process differs from working on a hierarchical
team.
</p>
<ul>
<li>
<a href="http://incubator.apache.org/learn/rules-for-revolutionaries.html">
Rules for Revolutionaries</a>
-- James Duncan Davidson
</li>
</ul>
<p>
Just using the products is a very important role.
We need people who will report bugs, contribute patches,
suggest
features, and so forth.
Your feedback helps the technology to evolve.
</p>
</answer>
</faq>
<faq id="mail">
<question>Joining the Mailing Lists</question>
<answer>
<p>
There are a variety of ways to participate.
Regardless of how you choose to participate,
we suggest you join our mailing lists.
</p>
<p>
Before joining any Apache mailing list, please be sure to
read the
<a href="mail.html#Guidelines">Mailing List Guidelines</a>
.
If you have read and understood these guidelines, you are
welcome to
<a href="mail.html#Subscribing">join the Struts mailing
lists</a>
.
</p>
<p>
Before posting a new question, be sure to consult one of
the
<a href="mail.html#Archives">
<strong>Mailing List Archives</strong>
</a>
and the very excellent
<a href="http://www.catb.org/~esr/faqs/smart-questions.html">
How To Ask Questions The Smart Way</a>
by Eric Raymond.
</p>
<p>
Please do be sure to
<a href="http://expita.com/nomime.html">turn off
HTML</a>
in your email client before posting.
</p>
</answer>
</faq>
<faq id="corp">
<question>What can my company do to help support Apache
Struts?</question>
<answer>
<p>
Apache Struts is an all volunteer product.
Our customers are the volunteers who donate their time and
energy to
supporting the product.
If you want to support Struts, and become one of our
customers,
then you need to get involved and become a volunteer.
</p>
<p>
Our challenge to any team using an Apache Struts product
is to donate the time of one team member
one afternoon a week (or more if you can spare the
resources).
Have your team member browse
<a href="#bugs">Bugzilla</a>
for any issues
without a
<a href="#patches">patch</a>
or unit test,
and
<a href="#contribute">add the patch or test</a>
.
Please note that we do not use @author tags in our
JavaDocs and
documentation.
If your patch includes an @author tag, we would have to
ask that it be removed.
</p>
<p>
If an Apache Struts product doesn't do what
<em>you</em>
want,
it's up to
<strong>you</strong>
to step up and propose the patch.
If an Apache Struts product doesn't ship as often as you
would like,
it's up to you to step up with the tests and fixes that
get a release out
the door.
(
<a href="http://jakarta.apache.org/site/contributing.html">
Like Craig
McClanahan did for Tomcat.</a>
)
</p>
<p>
If Struts does do what you want, help others become
involved by turning your
war stories into FAQs and how-tos that we can make part of
the
<a href="#documentation">documentation</a>
.
The mailing list is very active and
trundling through the archives is no picnic.
We can always use volunteers who can reduce the best
threads
to coherent articles we can share with others.
</p>
<p>
We don't sell Struts for money, but anyone who wants to be
our customer
can pay us back by donating the time and energy that money
represents.
</p>
</answer>
</faq>
<faq id="patches">
<question>How do I create a patch?</question>
<answer>
<p>
A patch is a machine-readable script that can
automatically
recreate a change to a text file, including source code
and
documentation.
The patch format is also human-readable.
Developers often pass patches around to discuss a change
before
applying it to the main repository.
</p>
<p>
The best way to affect a change to the source code or
documentation
is to provide a patch.
Apache Struts committers can then review your patch and
decide
whether to apply it to the main repository.
</p>
<p>
To create a patch, you first have to
<a href="downloads.html#Source_Code">
checkout</a>
a copy of the sourcecode or documentation from the main
repository.
You can then change your copy, and create the patch using
a simple
<a href="http://subversion.org/">Subversion</a>
command, like this:
</p>
<p>
<code>svn diff Main.java &gt;&gt; patchfile.txt</code>
</p>
<p>
Then, create a
<a href="#bugs">Bugzilla
report</a>
about the change, and attach the patch file.
</p>
<p>
Some Apache projects ask that you to submit your patch to
the mailing
list.
We would prefer that you create a
Bugzilla report and then attach the patch to the report.
To do this, you must first create the report,
and then modify the report to add your patch.
We realize this is a bit clumsy, but it keeps us from
losing things,
and helps to ensure that your patch will be attended.
</p>
<p>
The
<a href="http://www.netbeans.org/community/contribute/patches.html">
NetBeans community</a>
also has a helpful section on the
subject of creating patches.
</p>
</answer>
</faq>
<faq id="bugs">
<question>How can I report bugs or suggest features?</question>
<answer>
<p>
Tracking of bug reports and enhancement suggestions for
Apache Struts
subprojects is handled
through the
<a href="http://issues.apache.org/bugzilla">Apache Bug
Database</a>
(Bugzilla).
Please select
<strong>Struts</strong>
from the product list, along with
the details of which component of Struts you feel this
report
relates to, and details of your operating environment.
You will automatically be notified by email as the status
of your bug or
enhancement report changes.
Please be sure to read
<a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
How to
Report Bugs Effectively</a>
before posting.
</p>
<p>
You can research and report outstanding fixes and feature
suggestions
using Bugzilla.
If you are unsure if this is an actual problem,
feel free to bring it up on the list first.
But to be sure that an issue is resolved, read
<a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
How to Report Bugs Effectively</a>
and report it to
<a href="http://issues.apache.org/bugzilla">
<strong>Bugzilla</strong>
</a>
.
</p>
<p>
If you can't write a
<a href="#patches">patch</a>
to fix your bug,
a unit test that demonstrates the problem is also welcome.
(And, of course, unit tests that prove your patch works
are equally welcome.)
</p>
<p>
If your bug or feature is already in Bugzilla,
you can vote for the issue and call more attention to it.
Each user can cast up to six votes at a time.
</p>
<p>
If there is a patch attached to the issue, you can also
try applying
to your local copy of Struts, and report whether it worked
for you.
Feedback from developers regarding a proposed patch is
really quite
helpful.
Don't hesitate to add a "works for me" note to a ticket
if you've tried the patch yourself and found it useful.
</p>
<p>
Feature suggestions are also maintained in the
<a href="http://issues.apache.org/bugzilla">Bugzilla
database</a>
.
</p>
<p>
For your convenience, here are some common Bugzilla
queries:
</p>
<ul>
<li>
<a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;product=Struts&amp;order=bugs.bug_id">
Open reports</a>
</li>
<li>
<a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;email1=&amp;emailtype1=substring&amp;emailassigned_to1=1&amp;email2=&amp;emailtype2=substring&amp;emailreporter2=1&amp;bugidtype=include&amp;bug_id=&amp;changedin=&amp;votes=3&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;product=Struts&amp;short_desc=&amp;short_desc_type=allwordssubstr&amp;long_desc=&amp;long_desc_type=allwordssubstr&amp;bug_file_loc=&amp;bug_file_loc_type=allwordssubstr&amp;keywords=&amp;keywords_type=anywords&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=&amp;cmdtype=doit&amp;order=Bug+Number">
Open reports with at least 3 votes</a>
</li>
<li>
<a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;bug_severity=Blocker&amp;bug_severity=Critical&amp;bug_severity=Major&amp;bug_severity=Normal&amp;bug_severity=Minor&amp;email1=&amp;emailtype1=substring&amp;emailassigned_to1=1&amp;email2=&amp;emailtype2=substring&amp;emailreporter2=1&amp;bugidtype=include&amp;bug_id=&amp;changedin=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;product=Struts&amp;short_desc=&amp;short_desc_type=allwordssubstr&amp;long_desc=&amp;long_desc_type=allwordssubstr&amp;bug_file_loc=&amp;bug_file_loc_type=allwordssubstr&amp;keywords=&amp;keywords_type=anywords&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=&amp;cmdtype=doit&amp;order=bugs.bug_id">
Open problem reports</a>
<ul>
<li>
<a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;product=Struts&amp;bug_severity=Blocker&amp;bug_severity=Critical&amp;bug_severity=Major&amp;order=bugs.bug_id">
major problem reports</a>
</li>
<li>
<a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;product=Struts&amp;bug_severity=Blocker&amp;bug_severity=Normal&amp;bug_severity=Minor&amp;order=bugs.bug_id">
normal/minor problem reports</a>
</li>
</ul>
</li>
<li>
<a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;product=Struts&amp;bug_severity=Enhancement&amp;order=Bug+Number">
Open enhancement reports</a>
<ul>
<li>
<a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;bug_severity=Enhancement&amp;email1=&amp;emailtype1=substring&amp;emailassigned_to1=1&amp;email2=&amp;emailtype2=substring&amp;emailreporter2=1&amp;bugidtype=include&amp;bug_id=&amp;changedin=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;product=Struts&amp;short_desc=&amp;short_desc_type=allwordssubstr&amp;long_desc=&amp;long_desc_type=allwordssubstr&amp;bug_file_loc=&amp;bug_file_loc_type=allwordssubstr&amp;keywords=PatchAvailable&amp;keywords_type=anywords&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=&amp;cmdtype=doit&amp;newqueryname=&amp;order=Bug+Number">
Patch Available</a>
</li>
</ul>
</li>
<li>
<a href="http://issues.apache.org/bugzilla/buglist.cgi?bug_status=RESOLVED&amp;resolution=LATER&amp;resolution=REMIND&amp;product=Struts&amp;order=bugs.bug_id">
Reports to be handled "LATER"</a>
</li>
</ul>
</answer>
</faq>
<faq id="contribute">
<question>How can I contribute to the Struts source
code?</question>
<answer>
<p>
A very good place to start is by
<strong>reviewing the list of open issues</strong>
and pending feature suggestions (
<a href="#bugs">Bugzilla</a>
).
If you see an issue that needs a patch you can write,
feel free to annex your patch.
If you seen an issue that needs a unit test to prove its
fixed,
feel free to annex your test case.
If someone has posted a patch to an issue you'd like to
see resolved,
apply the patch to your local development copy of Struts.
Then let us know if it works for you, and if it does,
cast your vote for the issue and its patch.
</p>
<p>
If none of the pending issues scratch your itch,
another good place to start is by
<strong>contributing unit tests</strong>
for existing features (even those that still work).
</p>
<p>
You can upload a proposed
<a href="#patches">patch</a>
to either the code or documentation by creating a feature
suggestion
in
<a href="#Bugs">Bugzilla</a>
.
<strong>After creating the ticket</strong>
, you can go back and upload a
file containing your patch.
</p>
<p>
Our current approach to
<a href="kickstart.html#tests">unit testing</a>
works fairly well for exercising most method-level stuff,
but does
not really address situations of dynamic behavior -- most
particularly the
execution of custom tags for Struts.
You can try to fake what a JSP container does, but a much
more reliable
testing regime would actually execute the tag in a real
container.
For that purpose, we use the
<a href="http://jakarta.apache.org/cactus">Cactus</a>
testing framework,
which re-executes the JUnit-based tests as well to make
sure that nothing
bad happens when you switch environments.
Right now, there are very few dynamic tests; ideally, we
will have tests
for every tag, that cover every reasonable combination of
tag attribute
values (yes, that's a tall order -- the totally lines of
test source code
will undoubtedly exceed the totally lines of code in the
framework itself
if we achieve this).
</p>
</answer>
</faq>
<faq id="documentation">
<question>How can I contribute to the
documentation?</question>
<answer>
<p>
The documentation is maintained in the repository
under
the
<code>xdocs</code>
folder for the subproject.
To build just the documentation for a subproject,
change to the subprojects trunk directory and run
<code>maven site</code>
.
The Maven build compiles the site and stores the
output
under
<code>target/docs/</code>
.
</p>
<p>
Procedurally, the only difference between patching
documentation and
software is that the docs are kept in XML rather than
Java
source code.
Otherwise, all the same instructions pertain.
</p>
<p>
If you would like to help with the documentation, it
is
important to
provide patches and new pages in the XML source.
Otherwise, some other volunteer will have to do this
for
you, and it may
never get done.
(Sad but true.)
</p>
<p>
If you are submitting new material, it is important to
decide exactly
where you would put this in relation to the rest of
the
documentation.
Again, someone has to figure that out before it can be
added,
and that someone might as well be you.
</p>
<p>
If you are making a substantial contribution, such as
a
new HOW-TO,
please consider submitting a document in the XML
format we
use.
This will make it easier to add your contribution to
the
official
documentation so that it becomes part of a Struts
distribution.
</p>
<p>
The trick to getting started is to download the
nightly
build and try
building the subproject's site.
Then try adding your own XML page under xdocs/ to see
if
the build succeeds.
If it doesn't, it will report where the bad element
is,
much like it reports
where a bad programming expression is.
If it does, then your page should be available under
target/documentation/.
</p>
<p>
To display markup, substitute &amp;lt; for &lt;.
The unmatched trailing > will be ignored.
Since it is XML, all elements also need to closed.
So elements like &lt;br> and &lt;hr> need to set out
as
&lt;br/> and &lt;hr/>.
</p>
<p>
Also watch for the length of code samples - these do
not
wrap.
If a line is too long,
it will force the right margin out past the edge of
the
screen or
printed page.
</p>
<p>
You can also post documentation to the
<a href="wiki.apache.org/struts/">Struts Wiki</a>
.
</p>
</answer>
</faq>
<faq id="release">
<question>So when is the next release coming out?</question>
<answer>
<p>
Here is the truth regarding releases:
</p>
<p>
Apache products are released on the basis of merit,
and ~not~ according to a strict timetable.
The volunteers devote whatever time they can to work
on
the product.
But all volunteers have real jobs and real lives, that
do
take precedence.
Since Struts does not have paid personnel working on
the
project,
we simply cannot make date-oriented commitments.
</p>
<p>
The bottom line is that Apache takes releases very
seriously.
We do not compromise the quality of our software by
watching the calendar
(and then ship something ready or not).
A release is ready when it is ready.
</p>
<p>
That may sound flip, but it ~is~ the truth.
The delivery of production-quality, leading-edge
software
is
not something anyone can prognosticate.
If anyone tries, they are lying to you.
That, we won't do ;-)
</p>
<p>
What we ~will~ do is release all of our development
software as soon as
it is developed.
This way you can judge for yourself how quickly the
development is
proceeding, and whether what is being developed will
meet
your needs.
If you need a feature right now, you can use the
nightly
build, or roll
your own patch.
There are no internal code repositories, private
development lists,
secret chat rooms, or conference calls.
What you see is what we got.
If you are following the DEV list, then you know
everything the
developers know.
Really, you do.
</p>
<p>
<em>So, what do you tell your team?</em>
If you can ship your application based on the nightly
build of your choice,
then consider that an option.
You can still ship yours, even if we don't ship ours,
and you will have access to all the latest patches or
enhancements.
(Just like we were working down the hall.)
If you can only ship your application based on a
release
build of Struts,
then you should base your development on the release
build
of Struts,
and keep an eye on what is coming down the pipeline.
This way you are at least forewarned and forearmed.
</p>
</answer>
</faq>
<faq id="release_help">
<question>What can I do to help the next release
along?</question>
<answer>
<ul>
<li>
Most importantly, download the latest nightly
build or
development release
and test it against your own applications.
Report any and all issues or suspected issues to
<a href="http://issues.apache.org/bugzilla">
Bugzilla</a>
.
The sooner we resolve any problems, the fewer
betas or
release candidates
we will have to distribute before we are done.
(How do we know when we're done? -- When we run
out of
issues =:o)
The sooner we find them, the sooner we are done.)
</li>
<li>
<strong>Contribute
<a href="kickstart.html#tests">unit tests</a>
</strong>
.
The closer we get to a release, the more we worry
about breaking something.
The more tests we have, the more confident we can
be
when applying patches.
Tests that prove that a pending issue is actually
a
bug are the most
welcome ones.
But we are eager for any and all tests for any and
all
features,
even those that still work =:0).
</li>
<li>
<strong>Review the list of issues</strong>
at
<a href="#bugs">Bugzilla</a>
.
If there are any to which you can respond, please
do.
If there any patches posted, feel free to test
them
your system,
report the results, and cast your vote if they
work.
</li>
<li>
<strong>Confirm an issue's category and
status</strong>
.
Newbies often post feature suggestions or
help-desk
questions as "bugs".
This bloats the list of fixes we (apparently) need
to
apply before the next
beta, making it hard to see the forest for the
trees.
If an issue doesn't seem to be categorized
correctly,
exercise your best judgment and change it.
If one ticket seems like a duplicate of another,
go ahead and enter the change.
Every modification to the ticket is echoed to the
DEV
list and
automatically subjected to peer review.
Err on the side of doing.
</li>
<li>
Use Bugzilla to
<strong>vote for issues</strong>
you feel should be handle first.
If an issue on your ballot doesn't include a
patch,
feel free to try coding one yourself.
(In a meritocracy, patches are the only votes that
matter.)
Dozens of developers have contributed code or
documentation to Struts.
You can too =:0)
</li>
<li>
<strong>Answer questions on the user
list.</strong>
The Committers only have a limited amount of time
to
volunteer.
If Developers are supporting each other on the
lists,
the Committers have more time to spend on the next
release.
</li>
</ul>
</answer>
</faq>
<faq id="decides_help">
<question>How can I help make the decisions?</question>
<answer>
<p>
A guiding principle of the Apache Software Foundation is
"them that do the work, make the decisions".
This phrase is actually a double-entendre.
A project will make some decisions by voting (very few),
but the real decisions are made when a volunteer actually
does the
work.
Unless someone volunteers to do the work,
other decisions are meaningless.
</p>
<p>
In an ASF project, like Apache Struts,
volunteers who make sustained contributions to the project
are invited to become "Committers".
In due course, Committers are invited to join the Project
Management
Committee (PMC).
A goal of the ASF is for all Committers to be on the PMC.
</p>
<p>
By "sustained", we mean that an individual has been active
in the project for at least six months.
The contributions should come in the form of both patches
(to code or documentation), and posts to the mailing
lists.
Patches must be competent and accepted into the
repository.
Posts must be consistently helpful, friendly, and
collaborative.
The most important characteristic in a prospective
Committer is an
amicable demeanor that fosters goodwill.
</p>
<p>
As PMC members take note of Struts developers who meet our
qualifications, one of us will call for a vote on the
internal
PMC maining list.
(This usually happens when someone gets tired of applying
the volunteer's patches!)
The internal list is rarely used, and it is never used for
development discussions.
If the PMC vote passes, we will send the developer a
invitation
privately, to give the individaul a chance to accept or
discretely
decline.
If the candidate accepts,
the PMC will announce the new member on the dev list.
</p>
<p>
For more about decision-making, see
"
<a href="http://apache.org/foundation/how-it-works.html">
How the ASF Works</a>
" and the
<a href="bylaws.html">Apache Struts Charter</a>
.
For more about project infrastructure,
see "Project Maintenance and Resources" in the
<a href="http://wiki.apache.org/struts/">Apache Struts
wiki</a>
.
</p>
</answer>
</faq>
</part>
<part>
<p class="right">
<strong>Next:</strong>
<a href="mail.html">Mailing Lists</a>
</p>
</part>
</faqs>