ok. added you, you should now be able to edit pages...
On 01.10.2010 15:51, Josh Canfield wrote:
Sure, its joshcanfield. That's what my Apache user name should be as well.
Thanks.
On Oct 1, 2010 12:27 AM, "Ulrich Stärk"<[email protected]> wrote:
Can you tell me your confluence user name, I'll add you to the
tapestry-committers group.
Am 01.10.2010 um 03:27 schrieb Josh Canfield<[email protected]>:
Ah. I thought I needed my Apache account. I'm signed up for cwiki now and
I'll just fix it next time! :)
On Sep 30, 2010 5:58 PM, "Kalle Korhonen"<[email protected]>
wrote:
I see - but cwiki accounts are separate from Apache accounts, so just
sign
up.
Kalle
On Thu, Sep 30, 2010 at 5:52 PM, Josh Canfield<[email protected]>
wrote:
Yep, but I'm still waiting for my account...
On Sep 30, 2010 4:52 PM, "Kalle Korhonen"<[email protected]>
wrote:
Fixed. Faster to fix yourself than send an email, no?
Kalle
On Thu, Sep 30, 2010 at 3:31 PM, Josh Canfield<[email protected]
wrote:
typo in Copyright section: "try to check the coyright date"
On Thu, Sep 30, 2010 at 2:49 PM,<[email protected]> wrote:
Developer Bible<
https://cwiki.apache.org/confluence/display/TAPESTRY/Developer+Bible>
Page
*added* by Howard M. Lewis Ship<
https://cwiki.apache.org/confluence/display/~hlship>
This is a semi-random outpouring of thoughts related to being a
Tapestry
committer.
IDE IntelliJ
It's a free license for all committers and it's just better. Yes,
the
first
few days
can be an unpleasant fumble because everything is almost, but not
quite,
familiar. Pretty soon you'll love IDEA and
recognize that Eclipse has been bending you over and doing
unspeakable
things.
There are shared code formatting settings in
*<support/idea-settings.jar*>.
This will prevent
unexpected conflicts due to formatting.
Eclipse
Howard uses this ... because he can't manage to switch IDEs
constantly
(he
uses Eclipse for training). Lately
its gotten better.
Copyrights
All source files should have a copyright comment on top, except
where
such
a comment
would interfere with its behavior. For example, component template
files
omit the comment.
The year on the copyright should be updated as a file changes. As
you
are
reviewing your changes
before checking them in, try to check the coyright date, and add the
current year to the list if not
present.
Commit Messages
Always provide a commit message. I generally try to work off the
JIRA,
so
my commit message is often:
TAP5-1234: Make the Foo Widget more Ajax-tastic!
It is *very important* to include the JIRA issue id in the commit.
This
is
used in many places:
JIRA links issues to the SVN commits for that issue (very handy for
seeing
what changed
as part of a bug fix). The Hudson CI server does as well, and will
actually
link SVN commits to issues after
succesfully building.
JIRA Procedures
All Tapestry committers should be registerred with JIRA and part of
the
tapestry-developers JIRA group.
I work the following JIRA list: JIRA Work Queue<
https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12311597
.
Ideally, we would always work top priortity to low priority. I
(Howard)
sometimes jump out of order,
if there's something cool to work on that fits in an available time
slot.
Alternately, you are always
allowed to change the priority of a bug before or as you work it.
Starting work
When you start to work on an issue, make sure it is *assigned to
you*
and
use the *start progress*
option.
I often add comments about the state of the fix, or the challenges
in
creating a fix. This often spurs the Issue's adder to
provide more details.
I often update the issue description to make it more legible and
more
precise, i.e., "NPE in CheckUpdates"
might become "NullPointerException when checking for updates to
files
that
have been deleted". Verbose is good.
Closing bugs
Is it a bug fix without tests? *No.* In some cases, I write new
tests
to
prove that an issue is not valid and
then leave the tests in place – then close the bug as invalid.
A good plan is to write a test that fails then work the code until
the
test
passes.
I'm also surprised by how often code works in a unit test but fails
unexpectedly in an integration test.
As the G-Man says *"Expect unforseen consequences"*.
When you check in a fix, you should *close* the issue and make sure
the
*fix
release* is correct.
We're playing fast and loose – a better procedure would be to mark
the
bug
resolved and verify
the fix before closing it. That's ok, we have a community to double
check
our work .
For anything non-trivial, wait for the Hudson CI server to build. It
catches a lot of things ... such as
files that were not added to SVN. And even IntelliJ has a bit of
trouble
with wildly refactored code.
Hudson will catch all that.
Invalid issues and duplicates
Always provide comments about why_ an issue is invalid (*"A Ruby
implementation of Tapestry is out of scope for the project."*), or
at
least, a link to the duplicate issues.
Close the issue but *make sure the fix release is blank*. Otherwise,
the
issue _will be listed
in the release notes_, which we don't want.
Copyrights
The ASF copyright must appear on all Java source files. Technically
it
should appear on all non-binary
files in the repository.
As you make changes to files, update the copyright to add the
current
year
to the list. The goal is that the copyright
notice includes the year in which files change. When creating a new
file,
don't back date the copyright year ... starwith the current year.
Try
not to
change the copyright year on files that haven't actually changed.
IntelliJ has a great comparison view: Cmd-9 to see the local
changes,
the
Cmd-D to see the differences.
I whip through the changes (using Cmd-forward arrow) and make sure
copyrights are up to date as I review the changes
prior to a commit.
Public vs. Private/Internal
This is a real big deal. As long as code is in the internal package,
we
have a high degree of carte-blanche
to change it. As soon as code is public, we become handcuffed to
backwards
compatibility.
*Interfaces are public, implementations are private*. You can see
this
is
the bulk of the code, where
org.apache.tapestry5.services is almost all interfaces and the
implementations are
in org.apache.tapestry5.internal.services.
Many more services have both the interface and the implementation in
org.apache.tapestry5.internal.services.
We absolutely *do not* want to make Page or ComponentPageElement
public.
You will often see
public service facades that take a page name as a method parameter,
and convert it to a page instance before invoking methods
on internal services.
Evolving Components
We do not have a specific plan for this yet. Future Tapestry 5 will
add
features to allow clean renames
of parameters, and a way to deprecated and eventually remove
components.
Evolving Interfaces
Tapestry uses interfaces quite extensively.
Interfaces fall into two categories: service interfaces called by
user
code, and interfaces implemented by user code.
Internal interfaces may be changed at any time. That's why so much
is
kept
internal.
Service Interfaces
New methods may be added if absolutely necessary, but this should be
avoided if at all possible. Don't forget
the @since Javadoc annotation.
Consider having a stable public facade service whose implementation
calls
into one or more internal service.
User Interfaces
These should be frozen, no changes once released. Failure to do so
causes
*non-backwards compatible upgrade problems*;
that is, classes that implement the (old) interface are suddenly
invalid,
missing methods from the (new) interface.
Consider introducing a new interface that extends the old one and
adds
new
methods. Make sure you support both.
You can see this with ServiceDef and ServiceDef2 (which extends
ServiceDef). Yes this can be a bit ugly.
I actually have utility methods that convert from ServiceDef to
ServiceDef2, adding a wrapper implementation around
a ServiceDef instance if necessary:
Use of @since
When adding new classes or interface, or adding new methods to
existing
types, add an @since Javadoc comment.
Use the complete version number of the release in which the type or
method
was added: i.e., *...@since 5.1.0.3*.
Code Style
Yes, at one time I (Howard) used leading underscores for field
names.
I've
since changed my mind, but
I unfortunately infected other people; please try to make your code
blend
in when modifying existing source.
Long ago, Tapestry (3) code used the regrettable
"leading-I-on-interfaces"
style. Don't do that. Everything's an interface.
I prefer braces on a new line (and thus, open braces lined up with
close
braces), so that's what the default
code formatting is set up for. I sometimes omit braces for trivial
if
statements, such as {{ if (!test) return; }}.
I use a lot of vertical whitespace to break methods into logical
sections.
We're coding Java, not Pascal; I'd much rather see a few checks
early
on
with quick returns or exceptions than
have ten-levels deep block nesting just so a method can have a
single
return statement. In other words,
*else considered harmful*. Low code complexity is better, more
readable,
more maintainable code.
I don't bother alphabetizing things, because I have an IDE that lets
me
jump around easily.
*Final is the new private.* Final fields are great for
multi-threaded
code. Especially when creating
service implementations with dependencies, store those dependencies
into
final fields. Once we're all running
on 100 core workstations, you'll thank me. Seriously, Java's memory
model
is seriously twisted stuff, and
assigning to a non-final field from a constructor opens up a tiny
window
of
non-thread safety.
Comments
Comments are overwhelmingly important. Try to capture the *why* of a
class
or method. Add lots
of links, to code that will be invoked by the method, to related
methods
or
classes, and so forth. For instance,
I'll often have an annotation, a worker class for the annotation,
and
a
related service all cross-linked.
Comment the *interfaces* and don't get worked up on the
*implementations*.
Javadoc does a perfectly
good job of copying interface comments to implementations, so this
falls
under the *Dont Repeat Yourself*
guideline.
Be very careful about documenting what methods can accept null, and
what
methods may return null. Generally
speaking, people will assume that null is not allowed for parameter
and
method will never return null, unless
it is explicitly documented that null is allowed (or potentially
returned).
Documentation
Try and keep the documentation up-to date as you make changes; it is
*much
* harder to do so later. This is now much easier using the
Confluence
wiki
(you're reading it ).
Documentation is the *#1 criticism* of Tapestry!
Class and Method Naming Conventions
aming things is hard. Names that make sense to one person won't to
another.
hat being said, I've tried to be somewhat consistent with naming.
Not
perfectly.
Factory, Creator
A factory class creates new objects. Methods will often be prefixed
with
"create"
or "new". Don't expect a Factory to cache anything, it just creates
new
things.
Source
A source is a level up from a Factory. It *may* combine multiple
factories
together.
It *usually* will cache the result. Method are often prefixed with
"get".
Find vs. Get
For methods: A "find" prefix indicates that a non-match is valid and
null
may be returned.
A "get" prefix indicates that a non-match is invalid and an
exception
will
be thrown
in that case (and null will never be returned).
Contribution
A data object usually associated with a Tapestry IoC service's
configuration.
Filter
Part of a pipeline, where there's an associated main interface,
and the Filter wraps around that main interface. Each main interface
method is duplicated in the Filter, with an extra parameter used
to chain the interface.
Manager
Often a wrapper around a service configuration, it provides access
to the contributed values (possibly after some transformation).
To
A method prefix that indicates a conversion or coersion from one
type
to
another. I.e., toUserPresentable().
Worker
An object that peforms a specific job. Workers will be stateless,
but
will
be passed
a stateful object to perform some operation upon.
Builder
An object whose job is to create other objects, typically in the
context
of
creating a core service implementation for a Tapestry IoC service
(such
as
PipelineBuilder
or ChainBuilder).
Support
An object that provides supporting operations to other objects; this
is
a
kind of "loose aggregation".
Parameters
A data object that holds a number of related values that would
otherwise
be
separate
parameter values to a method. This tends to streamline code
(especially
when using
a Filter interface) and allows the parameters to be evolved without
changing the method signature.
Strategy
An object that "plugs into" some other code, allowing certain
decisions
to
be deferred
to the Strategy. Often a Strategy is selected based on the type of
some
object
being operated upon.
Context
Captures some stateful information that may be passed around between
stateless services.
Constants
A non-instantiable class that contains public static fields that are
referenced in multiple places.
Hub
An object that allows listeners to be registered. Often includes a
method
prefixed with "trigger"
that will send notifications to listeners.
Implement toString()
Objects that are exposed to user code should generally implement a
meaningful toString() method.
And that method should be tested.
Subclassing
You'll notice there isn't a lot of inheritance in Tapestry. Given
the
function of the IoC container,
it is much more common to use some variation of *aggregation* rather
than
*inheritance*.
Where subclassing exists, the guideline for constructor parameters
is:
the
subclass should include all
the constructor parameters of the superclass, in the same positions.
Thus
subclass constructor parameters
are appended to the list of super-class constructor parameters.
Change Notification Preferences<
https://cwiki.apache.org/confluence/users/viewnotifications.action>
View Online<
https://cwiki.apache.org/confluence/display/TAPESTRY/Developer+Bible>
--
--
http://www.bodylabgym.com - a private, by appointment only,
one-on-one
health and fitness facility.
--
http://www.ectransition.com - Quality Electronic Cigarettes at a
reasonable
price!
--
TheDailyTube.com. Sign up and get the best new videos on the internet
delivered fresh to your inbox.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
