So you've received commit rights to the JSPWiki SVN? First of all, welcome! This has been a long road, and it's great to have more people traveling the same road.

Overall JSPWiki quality principles#

JSPWiki has always been fairly straightforward, that is, we usually try to steer away from overly complicated patterns, and try to always keep code readability at maximum.

  • Keep your code readable. It is important that we all keep the codebase looking roughly similar - therefore, please read and be intimately familiar with the JSPWikiCodingStandard. That page also has ready-to-use Eclipse settings.
  • Don't trick yourself. While relying on obscure standard features are cool, it's probably better that you write boring, dull-looking code and implement cool stuff, rather than use cool code to implement boring things.
  • Think more about the APIs than code. If you are adding something of generic value, try to think of a nice API for it. Even if it does not become an API as such (at least immediately), think about it as if it was something that someone else had written, and whether you would enjoy using that API.
  • Create unit tests. When you want to replicate a bug - write an Unit test. When you want to test a new feature, write an Unit test.
  • Keep external dependencies to a minimum. Getting into JAR hell is not fun, so you will need to be especially careful when bringing in dependencies that bring in other dependencies. Please discuss all dependency additions on the issue tracker or the dev-list first!
  • It's okay to muck around with other people's code, if they're not good enough in your opinion. Especially this means that it's okay to add comments to other people's code, since this will probably increase everybody else's understanding of it.
  • If you use Eclipse, please use the Checkstyle plugin to find out bugs. You can find a tuned config under doc/eclipse/jspwiki-checkstyle.xml
  • Running FindBugs regularly is also a great idea.
  • It never hurts to ask for an opinion on the dev-list.

Things to do before committing#

  • Make sure your code compiles. THERE MUST NOT BE COMPILATION ERRORS EVER IN SVN. It's okay if your code does not work, just make sure it compiles.
  • Run the Unit tests (and webtests, if you've done anything bigger than a few lines). If you've accidentally broken something you shouldn't have, then fix it. If you *know* that you're breaking something, fix the tests.
  • Bump the version (in Release.java). Please see the VersioningProposal on which version number follows which one.
  • Add a suitable ChangeLog entry. See below for some description.
  • Commit a feature, not many features. It's better if you can commit single feature, because that makes it easier for example to create a patch out of it for inclusion in some other branch.

What is the difference between ReleaseNotes, ChangeLog, SVN commit logs and JIRA ChangeLog#

The most basic unit is the SVN commit log. This is where you note even the minute changes, so that other committers know what you're up to. It's okay to say things from "fixed typos in javadocs" to "imported Andrew's massive megapatch for JSPWIKI-XXX". In general, these should be per feature.

The next level is the ChangeLog. Whenever you commit a new build, you can put lots of description into the ChangeLog about what really, really happened and how does that impact anyone else. You can think of it that the ChangeLog is targeted at everyone on the -dev -list - that is, everyone who's interested in what is going on in JSPWiki. You can think of it as a shared blog for developers.

The ReleaseNotes is then something that gets collected out of the ChangeLog. It's sort of the "marketing version" of the ChangeLog, targeted at the -users -list people. It's a high overview of all the new features, fixed issues and gotchas you need to be aware of. The ReleaseNotes are the ones you would arm your sales guy with (if we had one).

The JIRA ChangeLog - that is, the JIRA fixed issues list is something that gets attached to the ReleaseNotes. It provides a public view to things which have been reported and/or fixed, but because not everything goes through JIRA, it is often incomplete.

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-2) was last changed on 30-Nov-2008 18:33 by Janne Jalkanen