How To Contribute
Contributing to an open source project is not just writing code. The aim is to improve the project and there are plenty of ways to do it.
- 1 Source Control Management
- 2 Be Involved
- 3 Improve the Documentation
- 4 Report bug/feature request
- 5 Contributing Code (Features, Bug Fixes, Tests...)
Source Control Management
WebLab uses SVN as its Source Control Management (SCM) system. To check out sources :
svn checkout svn://svn.forge.objectweb.org/svnroot/weblab
Or you can simply browse the source through the OW2 SVN browser on WebLab project.
Sources are built using Maven. Read the developer guide for more details.
Some additional links :
- Javadoc of API
- Continuous Integration with Bamboo
- Issue tracker using JIRA
- Repository Management Policy
- Code Conventions
The first step is to be involved in the project. The best way to to join the mailing lists.
- The user mailing list at email@example.com: this list is open to every one. It should be used at first to ask questions about the WebLab. One excellent way to start contributing is to help other people by answering on the mailing list.
- The development mailing list at firstname.lastname@example.org: this list is a restricted one, open to people that are already part of the development process.
Please keep discussions about the WebLab and its component on the list so that everyone benefits. Emailing individual committers with questions about specific issues is discouraged.
Moreover, user mailing list is archived, you can search in old discussions at: archives.
Improve the Documentation
The WebLab can always have better and more documentation targeted to both end users or developers. This Wiki miss for sure some tutorial or specific documentation on components. If you want, you can request editing right. If you see a gap in documentation, fill it in. Even if you don't know exactly what to write about, you can ask on the user list. If you are using the WebLab, it means that you have managed to master various technologies associated with WebLab, if so, other people may need your help.
Report bug/feature request
The WebLab has a dedicated bug tracker system at: http://jira.ow2.org/browse/WEBLAB. Prior to submiting any bug or feature requests, it would be apreciated to discuss it on the mailing list. But if you know what you are doing and are sure that you have encountered a real bug you can submit it directly. You will need to request an OW2 account first at http://jira.ow2.org/secure/Signup!default.jspa.
You are also encouraged to comment on existing issues in Jira, for instance, if you are able to reproduce the bug on another environment. Please also vote for issues that are of a top priority for you. The more comments and votes, the more involved will the development team be.
Contributing Code (Features, Bug Fixes, Tests...)
This section identifies the "optimal" steps community members can take to submit changes or improvements to the WebLab code base. This could be new features, bug fixes optimizations of existing features, or tests of existing codes to prove it works as advertised (and to make it more robust against possible future changes).
Please note that these are the "optimal" steps, and community members that don't have the time or resources to do everything outlined on this below should not be discouraged from submitting their ideas "as is" per "Yonik's Law of Patches"...
A half-baked patch in Jira, with no documentation, no tests and no backwards compatibility is better than no patch at all.
Just because you may not have the time to write unit tests, or cleanup backwards compatibility issues, or add documentation, doesn't mean other people don't. Putting your patch out there allows other people to try it and possibly improve it.
Getting the source code
See http://forge.ow2.org/plugins/scmsvn/index.php?group_id=357 Note that instead of downloading the whole trunk, you can select a specific module (a service for instance) by going down into the folder tree.
Set up your environment
Follow the code style guidelines
To ease the application of checkstyle rules we provided as part of the same project on the SVN two files that can be imported into Eclipse. One configures the formatter and the second one is a template for class file headings. See weblab-build-tools
Before you start, send a message to the developer mailing list (Note: you have to subscribe before you can post), or file a bug report in Jira. Describe your proposed changes and check that they fit in with what others are doing and have planned for the project. Be patient, it may take folks a while to understand your requirements.
Modify the source code and add some (very) nice features using your favorite IDE.
But take care about the following points:
- Code compatibility:
- All code should be compatible with Java 7.
- All public classes and methods should have informative Javadoc comments.
- Code should be formatted according to Sun's conventions with one exception:
- We have wide screen now. Feel free to use the 200 column that we allow ;-)
- Contributions should pass existing unit tests.
- New unit tests should be provided to demonstrate bugs and fixes (http://junit.org).
- You must implement a class that uses @Test annotations for all test methods. Please note, that we use JUnit v4.
- Define methods within your class whose names begin with test, and call JUnit's many assert methods to verify conditions; these methods will be executed when you run ant test (or mvn test). Please add meaningful messages to the assert statement to facilitate diagnostics.
- Place your class in the src/test/java tree.
- The java source code is in the directory src/main/java and the java test code is in the directory src/test/java.
Generating a patch
To generate a patch, run and save svn diff result between your project and the current version on the WebLab svn.
Run in your project
svn diff > MyPatch.patch
Contributing your work
Finally, patches should be attached to a bug report in Jira.
Please be patient. Committers are busy people too. If no one responds to your patch after a few days, please make friendly reminders. Please incorporate others' suggestions into your patch if you think they're reasonable. Finally, remember that even a patch that is not committed is useful to the community.