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]
