<?xml version="1.0"?>
<document url="./helping.xml">
<properties>
<title>How to Help FAQ - Apache Struts</title>
</properties>

<body>

<section href="faq" name="How to Help FAQ"/>

<section href="contents" name="Index">

<p>

"You can't always get what you want / 
but if you try real hard / 
you might just find /
that you get what you need". 
<br/>
[Rolling Stones]
</p>

<ul>
    <li><a href="#corp">
    What can my company do to help support Struts?
    </a></li>
    <li><a href="#bugs">
    How can I report bugs or make feature requests?
    </a></li>
    <li><a href="#contribute">
    How can I contribute to Struts source code?
    </a></li>
    <li><a href="#documentation">
    How can I contribute to the documentation?
    </a></li>
    <li><a href="#release">
    So when is the next release coming out?
    </a></li>
    <li><a href="#release_help">
    How can I help the next release along?
    </a></li>
</ul>

</section>

<section href="corp" name="What can my company do to help support Struts?">

<p>
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 
<a href="http://jakarta.apache.org/site/getinvolved.html">get involved</a>
and become a volunteer.
</p>

<p>
Our challenge to any team using Struts 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="http://jakarta.apache.org/site/bugs.html">Bugzilla</a> for any issues 
without a patch or unit test, 
and add the patch or test.
If the patch is written on company time, 
and you want to give your company an author's credit, that's fine with us.
</p>

<p>
If Struts doesn't do what <em>you</em> want, it's up to <strong>you</strong> to step up 
and propose the patch.
If Struts 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.
</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 people who can reduce the best threads to coherent articles 
that we can put in the User Guide.
</p>

<p>
Some Apache products like you to submit your patch to the mailing list. 
We would prefer that you create a 
<a href="http://jakarta.apache.org/site/bugs.html">Bugzilla</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>
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>

</section>

<section href="bugs" name="How can I report bugs or make feature requests?">

<p>
You can research and report outstanding fixes and feature requests using
<a href="http://jakarta.apache.org/site/bugs.html">Jakarta Bugzilla</a>. 
If you are unsure if this is an actual problem, feel free to bring it up 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://jakarta.apache.org/site/bugs.html"><strong>Bugzilla</strong></a>.
</p>

<p>
Feature requests are also maintained in the Bugzilla database. 
</p>

<p>
<a href="http://jakarta.apache.org/site/source.html">Patches</a> are always
welcome. 
If you can't write a patch to fix your bug, a <a href="kickstart.html#tests">unit test</a>
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, <strong>you can vote</strong>
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 "me too" if you've tried the patch yourself.
</p>

</section>

<section href="contribute" 
    name="How can I contribute to the Struts source code?">

<p>
Struts is distributed by <a href="http://apache.org/">
The Apache Software Foundation</a>.
These are the same people who distribute the Apache Web server. 
Like all ASF projects, Struts is managed as a &quot;meritocracy&quot;, 
where everyone's contribution is welcome. 
Users can help other users the 
<a href="http://jakarta.apache.org/site/mail.html">mailing lists</a>,
<a href="http://jakarta.apache.org/site/bugs.html">report bugs</a>, and
<a href="http://jakarta.apache.org/site/bugs.html">request new features</a>. 
Developers can
contribute patches, new code, and documentation. 
The most active Developers may become
<a href="http://jakarta.apache.org/site/roles.html">Committers</a>, 
who make the actual decisions about Strut's codebase.
</p>

<p>
If you are new to open source development, see the
<a href="http://jakarta.apache.org/site/getinvolved.html">
How to get involved</a> page the main Jakarta site.
</p>

<p>
A very good place to start is by <strong>reviewing the list of open issues</strong> and 
pending feature requests (<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>
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>

</section>

<section href="documentation" 
    name="How can I contribute to the documentation?">

<p>
The only difference is that the documentation is kept in XML rather than Java
source code. 
Otherwise, all the same precepts and procedures pertain.
</p>

<p>
The trick to getting started is to download the nightly build and try building 
the documentation WAR. 
Then try adding your own XML page under doc/ 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>
The website portion of the package is the root directory of doc/. 
The User Guide portion is under the userGuide/ folder. 
If the material you'd to add doesn't fit right in with what's there, 
the best thing may to start a new section after the existing material. 
The navigation column can be found in the project.xml document.
</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>
The stylesheets we use are adequate, but could certainly be improved by an XML
guru, if you happen to one of those.
</p>

</section>

<section href="release" name="So when is the next release coming out?">

<p>
Here is the truth regarding releases:
</p>

<p>
Jakarta 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>
All Jakarta products must circulate a public beta before release. 
If a beta is not in circulation, 
then it's a good bet that a release is not forthcoming any time soon. 
Products sometimes go through several betas before final release. 
So if this is beta 1, then it still may not be released any time soon.
</p>

<p>
The bottom line is that Jakarta 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 private Subversion repositories or private development lists. 
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>

</section>

<section href="release_help" 
    name="What can I do to help the next release along?">

<ul>

<li>
  Most importantly, <strong>download the latest beta</strong> or release-candidate and 
  test it against your own applications. 
  Report any and all issues or suspected issues to 
  <a href="http://jakarta.apache.org/site/bugs.html">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 requests 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 handled
  first. 
  If an issue on your ballot doesn't include a patch, feel free to try coding 
  one yourself. 
  (At Jakarta, patches are the only votes that truly count.) 
  Well over <a href="../volunteers.html">thirty developers</a> have contributed 
  code or documentation to the product. 
  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>

</section>

<section href="decisions" 
    name="Who makes the final decisions regarding Struts">

<p>
The management of the Jakarta site, and the Struts product, is based on 
principles and practices used by creators of the Apache HTTPD server. 
Struts follows the 
<a href="http://jakarta.apache.org/site/guidelines.html">Project Guidelines</a>
on the main Jakarta site.
</p>

<p>If you are new to this style of development, 
the Apache HTTPD Dev list is available in a 
<a href="mailto:dev-digest-subscribe@httpd.apache.org">digest form</a>. 
Even if you are not working on the HTTPD server yourself, 
it is interesting to watch how the HTTPD team works on the server.
</p>

<p>
The Struts project has its own <a href="../using.html#Lists">Dev list</a>, 
where all of the decisions regarding Struts are made. 
Most development takes place via
<a href="http://jakarta.apache.org/site/proposal.html#decisions/voting/items">
Lazy Consensus</a>.
Committers post most changes to the product unilaterally, using their own best 
judgment, and only discuss or vote upon controversial matters. 
Another Committer can veto any change in an unreleased product with cause.
</p>

</section>
</body>
</document>