| <?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 "meritocracy", |
| 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 &lt; for <. |
| The unmatched trailing > will be ignored. |
| Since it is XML, all elements also need to closed. |
| So elements like <br> and <hr> need to set out as <br/> and <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> |