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]
