[CONF] Apache Tapestry Developer Bible
Bob Harner edited the page:
Developer Bible
Comment: Added spaces-over-tabs rule
...
Howard uses utility methods that convert from ServiceDef to ServiceDef2, adding a wrapper implementation around a ServiceDef instance if necessary:
Code Block
public static ServiceDef2 toServiceDef2(final ServiceDef sd)
{
if (sd instanceof ServiceDef2)
return (ServiceDef2) sd;
return new ServiceDef2()
{
public boolean isPreventDecoration()
{
return false;
}
public ObjectCreator createServiceCreator(ServiceBuilderResources resources)
{
return sd.createServiceCreator(resources);
}
. . .
};
}
...
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 Formatting
Yes, at one time Howard used leading underscores for field names. He has since changed my mind, but this 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 interfaceInstead, name the implementation class with an Impl at the end.
Howard prefers 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. It's okay to omit braces for trivial one-liner if statements, such as if (!test) return;.
Indent with 4 spaces instead of tabs.
Use a lot of vertical whitespace to break methods into logical sections.
...
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 the result ).
Documentation is was at one point the #1 criticism of Tapestry!
...
View Online Like View Changes
Stop watching space Manage Notifications
[CONF] Apache Tapestry Developer Bible
Bob Harner edited the page: Developer Bible Comment: Chagned SVN to Git ... 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 Gitcommits 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 Gitcommits to issues after succesfully building. ... 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 SVNGit. And even IntelliJ has a bit of trouble with wildly refactored code. Hudson will catch all that. ... View Online Like View Changes Stop watching space Manage Notifications This message was sent by Atlassian Confluence 5.0.3, Team Collaboration Software
[CONF] Apache Tapestry Developer Bible
Bob Harner edited the page:
Developer Bible
Comment: Updated intro paragraph
Wiki Markup
{float:right|background=""
{contentbylabel:title=Related Articles|showLabels=false|showSpace=false|labels=tapestry-dev}
{float}
This is a semi-random outpouring of thoughts related to being a Tapestry committerIDE choices, coding style and formatting, commit practices, naming conventions and other issues relevant to Tapestry committers contributers.
IDE Choices
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.
...
View Online Like View Changes
Stop watching space Manage Notifications
This message was sent by Atlassian Confluence 5.0.3, Team Collaboration Software
[CONF] Apache Tapestry Developer Bible
Developer Bible Page edited by Bob Harner Comment: Added links to idea-settings.jar and tapestry-indent-eclipse.xml Changes (2) ... Its a free license for all committers and its just better. Yes, the first few days can be an unpleasant fumble because everything is almost, but not quite, familiar. Pretty soon youll 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_. the [support directory|https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=support] (idea-settings.jar). This will prevent unexpected conflicts due to formatting. h3. Eclipse ... Howard uses this ... because he cant manage to switch IDEs constantly (he uses Eclipse for training). Lately its gotten better. As with IntelliJ, there are shared code formatting settings for Eclipse in the [support directory|https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=support] (tapestry-indent-eclipse.xml). h2. Copyrights ... Full Content Related Articles Page: Confluence Site Setup Page: Developer Bible Page: Release Process Page: Version Numbers Page: Developer Information Page: Building Tapestry from Source This is a semi-random outpouring of thoughts related to being a Tapestry committer. IDE Choices 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 the support directory (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. As with IntelliJ, there are shared code formatting settings for Eclipse in the support directory (tapestry-indent-eclipse.xml). Copyrights All source files should have the ASF copyright comment on top, except where such a comment would interfere with its behavior. For example, component template files omit the comment. 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 ... start with 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. You can whip through the changes (using Cmd-forward arrow) and make sure copyrights are up to date as you review the changes prior to a commit. Commit Messages Always provide a commit message. Howard generally tries to work off the JIRA, so his 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. Every committer is invited to look at the list of 'Review for closing' issues and review them as it contains probably outdated or no more valid issues. There's also a list of all Open issue about the project. Ideally, we would always work top priortity to low
[CONF] Apache Tapestry Developer Bible
Developer Bible Page edited by Massimo Lusetti Changes (4) ... All Tapestry committers should be registerred with JIRA and part of the tapestry-developers JIRA group. Howard works the following JIRA list: [JIRA Work Queue|https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hiderequestId=12311597]. Every committer is invited to look at the list of [Review for closing|https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hiderequestId=12317068] issues and review them as it contains probably outdated or no more valid issues. Theres also a list of all [Open|https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hiderequestId=12316792] issue about the project. Ideally, we would always work top priortity to low priority. Howard sometimes jump out of order, if theres 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. As a general rule issues which are _Invalid_ or _Wont_ _Fix_ shouldnt have a _Fix_ _version_. h3. Starting work ... Full Content Related Articles Page: Developer Bible Page: Confluence Site Setup Page: Release Process Page: Developer Information This is a semi-random outpouring of thoughts related to being a Tapestry committer. IDE Choices 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 the ASF copyright comment on top, except where such a comment would interfere with its behavior. For example, component template files omit the comment. 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 ... start with 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. You can whip through the changes (using Cmd-forward arrow) and make sure copyrights are up to date as you review the changes prior to a commit. Commit Messages Always provide a commit message. Howard generally tries to work off the JIRA, so his 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. Every committer is invited to look at the list of 'Review for closing' issues and review them as it contains probably outdated or no more valid issues. There's also a list of all Open issue about the project. Ideally, we would always work top priortity to low priority. 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. As a general rule issues which are "Invalid" or "Won't Fix" shouldn't have a "Fix version". Starting work When you start to work on an issue, make sure it is assigned to you and use the start progress option. Add comments about the state of the fix, or the
[CONF] Apache Tapestry Developer Bible
Developer Bible Page edited by Bob Harner Comment: Removed duplicate Copyright section, minor formatting, para wrapping and de-"I"-ifying Changes (92) ... h3. IntelliJ Its a free license for all committers and its just better. Yes, the first few days can be an unpleasant fumble because everything is almost, but not quite, familiar. Pretty soon youll love IDEA and recognize that Eclipse has been bending you over and doing unspeakable things. can be an unpleasant fumble because everything is almost, but not quite, familiar. Pretty soon youll 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. unexpected conflicts due to formatting. h3. Eclipse Howard uses this ... because he cant manage to switch IDEs constantly (he uses Eclipse for training). Lately its gotten better. its gotten better. h2. Copyrights All source files should have a the ASF copyright comment on top, except where such a comment would interfere with its behavior. For example, component template files omit the 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 copyright date, and add the current year to the list if not present. 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, dont back date the copyright year ... start with the current year. Try not to change the copyright year on files that havent actually changed. IntelliJ has a great comparison view: Cmd-9 to see the local changes, the Cmd-D to see the differences. You can whip through the changes (using Cmd-forward arrow) and make sure copyrights are up to date as you review the changes prior to a commit. h2. Commit Messages Always provide a commit message. I Howard generally try tries to work off the JIRA, so my his commit message is often: bq. 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. 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. h2. JIRA Procedures All Tapestry committers should be registerred with JIRA and part of the tapestry-developers JIRA group. I work Howard works the following JIRA list: [JIRA Work Queue|https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hiderequestId=12311597]. Ideally, we would always work top priortity to low priority. Howard sometimes jump out of order, if theres 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. Ideally, we would always work top priortity to low priority. I (Howard) sometimes jump out of order, if theres 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. h3. Starting work When you start to work on an issue, make sure it is _assigned to you_ and use the _start progress_ option. option. I often add Add comments about the state of the fix, or the challenges in creating a fix. This often spurs the Issues adder to provide more details. I often update the issue description to make it more legible and more precise, i.e., NPE in CheckUpdates Update the issue description to make it more legible and more precise if needed, i.e., NPE in CheckUpdates might become NullPointerException when checking for updates to files that have been deleted. Verbose is good. h3. Closing
[CONF] Apache Tapestry Developer Bible
Developer Bible
Page added by Howard M. Lewis Ship
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.
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
[CONF] Apache Tapestry Developer Bible
Developer Bible
Page edited by Kalle Korhonen
Changes (1)
...
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 copyright date, and add the current year to the list if not
present.
...
Full Content
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 copyright 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.
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
