You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by hu...@apache.org on 2004/01/27 11:33:58 UTC
cvs commit: jakarta-struts/doc/faqs helping.xml
husted 2004/01/27 02:33:57
Modified: doc/faqs helping.xml
Log:
Update advice re @author tags. Add more links to patch howtos.
Revision Changes Path
1.9 +175 -166 jakarta-struts/doc/faqs/helping.xml
Index: helping.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/faqs/helping.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- helping.xml 19 Sep 2003 22:09:42 -0000 1.8
+++ helping.xml 27 Jan 2004 10:33:57 -0000 1.9
@@ -14,10 +14,10 @@
<p>
-"You can't always get what you want /
-but if you try real hard /
+"You can't always get what you want /
+but if you try real hard /
you might just find /
-that you get what you need".
+that you get what you need".
<br/>
[Rolling Stones]
</p>
@@ -48,56 +48,64 @@
<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
+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,
+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.
+Please note that Struts does not use @author tags in our JavaDocs.
+If your patch includes an @author tag, we would have to ask that it be removed.
</p>
<p>
-If Struts doesn't do what <em>you</em> want, it's up to <strong>you</strong> to step up
+(For more about creating patches, see the
+<a href="http://jakarta.apache.org/site/source.html">Jakarta Project Guidelines</a>.
+The <a href="http://www.netbeans.org/community/contribute/patches.html">
+NetBeans community section</a> also has a helpful section on the same
+subject.
+</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
+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
+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
+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,
+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
+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>
@@ -107,22 +115,22 @@
<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://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.
+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.
+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.)
@@ -130,7 +138,7 @@
<p>
If your bug or feature is already in Bugzilla, <strong>you can vote</strong>
-for the issue and call more attention to it.
+for the issue and call more attention to it.
Each user can cast up to six votes at a time.
</p>
@@ -138,29 +146,30 @@
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.
+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>
</section>
-<section href="contribute"
+<section href="contribute"
name="How can I contribute to the Struts source code?">
<p>
Struts is distributed by the <a href="http://apache.org/">
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
+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>.
+<a href="http://jakarta.apache.org/site/bugs.html">request new features</a>.
Developers can
-contribute patches, new code, and documentation.
+contribute patches, new code, and documentation.
The most active Developers may become
-<a href="http://jakarta.apache.org/site/roles.html">Committers</a>,
+<a href="http://jakarta.apache.org/site/roles.html">Committers</a>,
who make the actual decisions about Strut's codebase.
</p>
@@ -171,21 +180,21 @@
</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,
+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>
+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>
@@ -193,59 +202,59 @@
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
+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"
+<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.
+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.
+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 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.
+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
+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>
@@ -264,127 +273,127 @@
<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,
+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.
+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).
+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 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 CVS's 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.
+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 CVS's 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,
+<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.
+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"
+<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)
+ 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,
+ <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,
+ <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
+ <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.
+ 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.
+ 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,
+ <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>
@@ -392,32 +401,32 @@
</section>
-<section href="decisions"
+<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
+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,
+<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.
+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.
+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>
---------------------------------------------------------------------
To unsubscribe, e-mail: struts-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: struts-dev-help@jakarta.apache.org