Table of Contents
- 1. Summary of development resources
- 2. Development Environment
- 2.1. Preliminars
- 2.2. Initial steps
- 2.3. Get the code: How to checkout the Kune code
- 2.4. Next step: install Eclipse
- 2.5. Eclipse configuration
- 2.6. Install Kune
- 2.7. GWT's Hosted Mode and SuperDev Mode
- 3. Some relevant docs for Kune development
- 4. Languages and frameworks used in Kune development
- 5. Notable dependencies
- 6. Coding
- 7. Some recommendations
- 8. Code preferences
- 9. Use of Mylyn in Eclipse
- 10. Testing
- 11. Code samples
- 12. UI dev
- 13. Kune maven repo
- 14. Making a Kune release
- 15. Changelog
- 16. License
- 17. Get in touch
KUNE DEVELOPER'S GUIDE
Summary of development resources
- Code: https://github.com/comunes/kune
- Bugs (send issues here): http://redmine.comunes.org
- Continuous Integration: http://ci.comunes.org
- Reviews (send your patches here): http://reviews.comunes.org
- Maven Repository: http://archiva.comunes.org
- Our lists: http://kune.cc/#kune.lists
- Our group in kune: http://kune.cc/#kune
This guide will help you to develop in Kune. It deals with the prerrequisites of Kune and the setup of its environment. You should follow each step carefully. Make sure you deal with the following initial steps and only afterwards proceed to the details of the installation of Kune. As mentioned in the subsection "1.7:Install Kune" of this guide, you will need by then the document INSTALL, where you will find the details of the installation.
Install some basic tools (if you don't have them). In Ubuntu, Debian and derivatives:
sudo apt-get install git maven2 mercurial
and Java 7:
sudo apt-get install openjdk-7-jdk
NOTE: we use Git for our code, Maven for its dependencies, and Wave In a Box (WIAB) uses Mercurial. Besides, you will need a modern browser such as Firefox or Chromium, and some extensions to live happier:
The previous link has also other more general information (texts and references) of interest for contributors.
Get the code: How to checkout the Kune code
Our code is in this Github: https://github.com/comunes/kune
Anonymous GIT Access
This project's GIT repository can be checked out through anonymous access with the following command(s).
git clone https://github.com/comunes/kune.git
The Eclipse IDE has some plugins for GIT and it's hightly recomended to use one, because it would get rid of file/package renaming and other refactorizations.
Next step: install Eclipse
Ensure Eclipse is configured to use Java 1.7.
The instructions below will give for granted you use Eclipse. Of course, you can use any other IDEs (in such case, please help us to improve this documentation).
Some mandatory plugins for Eclipse
From the Eclipse Marketplace (Help > Eclipse Marketplace (*)) install:
Google Plugin for Eclipse https://code.google.com/intl/en/eclipse/docs/getting_started.html (if available, install also the GWT Designer from the Google repository)
EGit plugin (Git for Eclipse)
Eclipse Java EE Developer Tools
(*): If the Marketplace does not appear in that menu, download the plugin "Marketplace Client" from the Install New Software > Your version repository > "General Purpose Tools" > Marketplace Client. Install and restart, and you will see Help > Eclipse Marketplace.
Optional maven-eclipse integration
Check: http://google-web-toolkit.googlecode.com/svn/trunk/samples/expenses/README-MAVEN.txt http://code.google.com/p/google-web-toolkit/wiki/WorkingWithMaven#Using_Maven_with_Google_Plugin_for_Eclipse
Check out if Kune's code includes Eclipse project definition files (i.e. '.project' & '.classpath') in the kune directory. (WARNING: if you imported manually the Kune source code into Eclipse, they were then created… but still you should run the following command.) If these files do not exist, then you need to run (again from the kune directory):
This generates .project and download necessary code jars (this download process is long, so take a rest).
After that, you can import the project in Eclipse (File > Import > Existing Projects into Workspace).
Also you have to set the variable M2_REPO (Eclipse: Window > Preferences > Java > Build Path > Classpath Variables > New) to the location of your local maven repo (in our case
/home/youruser/.m2/repository). (WARNING: It might exist already with an incorrect path. In that case, instead of "New" use "Edit").
(*) NOTE: We actually use
bin/mvn-eclipse.sh instead of a simple
mvn eclipse:eclipse to hack a little bit the .classpath, because
mvn eclipse:eclipse removes the GWT_CONTAINER line a the end of the .classpath. You can fix it from eclipse (anytime that we change the dependencies and you have to do a
mvn eclipse:eclipse), but we prefer to do it that way from the command line. In order to execute the script, run ./bin/mvn-eclipse.sh from the kune directory.
NOTE: If after bin/mvn-eclipse.sh the Eclipse project does not properly select the GWT SDK (throwing an error in the Build Path, showing an "unknown" SDK, or similar problem) then include and choose manually the GWT SDK 2.7.0.
Configure Google GWT Plugin
For now we are using GWT 2.7.0 (it usually will not match with the one from the eclipse GWT plugin) so probably you have to download that version of the SDK from: http://code.google.com/p/google-web-toolkit/downloads/list unzip (to any place you find appropriate), and add that SDK in Eclipse (Windows > Preferences > Google > Web Toolkit > Add).
WARNING: Do not use any other GWT SDK versions because our code (and dependencies) probably are not compatible with different versions and we should do a coordinated migration.
After that, right click Kune project in the "Package Explorer" > Google > WebApplication > WAR directory: set to src/main/webapp (after checking "This project has a WAR directory") and uncheck the "Launch and deploy from this directory".
Also in Kune project properties > Google > Web Toolkit > Check that you are using the 2.7.0 SDK.
The charset used in Kune is UTF8. In Eclipse, check the text-file enconding in Package Explorer > Properties of Kune project > Resource > Text file encoding.
You can change this globally in Eclipse Preferences > General > Workspace.
NOTE: Please don't send patches in other charsets.
Other recommended & suggested plugins for Eclipse
NOTE: When a URL repository is indicated, it should be added to Eclipse > Help > Install new software > Add
From the Eclipse Marketplace:
The FindBugs plugin (looks for bug patterns)
Mylyn (task-focused development)
From the Google repository (as you installed the "Google Plugin for Eclipse" before):
- The GWT Designer GUI Builder plugin (a great helper to work with GWT UiBinder)
From the repository http://pmd.sourceforge.net/eclipse
- The PMD Eclipse plugin (scans the code looking for potential problems).
From the repository http://redmin-mylyncon.sourceforge.net/update-site/N/
- Redmine Mylyn Connector (ideal to use in combination with Mylyn and a Redmine like the used by Kune)
Also maybe some other plugins are interesting such as:
AnyEditTools (to remove tabs and so on)
EGit for Mylyn (connecting EGit and Mylyn)
AutoDeriv (see our .derived file that works like .gitignore)
Other Eclipse info
Useful info about GWT and Eclipse (interesting if you have problems with number of open files or with the memory use): http://code.google.com/p/gwt-examples/wiki/gwtEclipseFaqs
Only after making sure the previous steps have been finished, you can proceed to the installation of the rest of Kune. For doing so, you need to follow the instructions of the document INSTALL. Afterwards you will be able to run Kune for the first time.
WARNING: The above paragraph means that the installation instructions are NOT in this document. Please, check out the referenced INSTALL document for the installation instructions, and come back here when those are finished.
GWT's Hosted Mode and SuperDev Mode
Before running hosted mode for the first time compile once with:
mvn compile -Dliquibase.should.run=false && mvn gwt:compile -P development
and deploy with:
NOTE: Run both from the "kune" directory.
Kune runs a specific jetty server (not necessary the one used by GWT), so we run the server and the client separately.
For now It's better not to use the "internal server" of GWT hosted mode because we need to control the version of the (jetty) server that we use, for compatibility reasons. This is why we run separately the client (hosted mode) and the server.
In the "bin" directory there are (mainly) three launch configurations, one for the server and one for the client: (1) "kune-server-via-mvn.launch" (2) "kune-client-superdev.launch" (3) "kune-client-embed-superdev.launch"
also there are some client launch equivalent to test the embeded functionality.
These configurations are Eclipse running configurations that are normally imported by Eclipse when you import the project (in GNU/Linux at least). See the "Run" and the "Run External" icons and menu options in the Eclipse toolbar to find these launchs. If they are not there, try to import them (in Eclipse: File > Import > Launch Configurations > select the launchs from the "bin" directory). Also you can try to fix the path for the "mvn" command (especially Windows users). Another option is to create a new launch to run a external "mvn exec:java" because the previous launch were created in GNU/Linux systems.
Run it! Launch the first, (1), (it's equivalent to mvn exec:java) to start the kune server. After that, launch the second (2) to start kune in superdev mode and connect to the previous server (that was launched with (1)). Use (3) to launch the superdev mode for test the embed system. Since then, in you are using (1) you will be able to make code modifications (in the client code), and refresh the browser to see the changes (with no compiling :) Changes in the server code would need compiling.
NOTE: It's easy to distinguish Client code from Server code, as Client has "client" in the package name, while Server has "server". There is also "shared" code.
NOTE: Compilation will be mandatory when you aim to build the DEB package. In this compilation, all languages (and not just English) should be used (compiling for production, not for development).
NOTE: If you want to run Server in debug mode, you should run "kune server via mvn with debug.launch" (then you will see the [DEBUG] comments in the Eclipse Console). If you want to run the Client in debug mode, you can run it using the Debug icon, as usual in Java programs.
NOTE: If you have errors or problems during compilation or launching, check out the TROUBLESHOOT file for help. If you are still unable to solve it, contact the Kune developers (http://kune.ourproject.org/contact/ ) and we'll try to help you.
Testing stop of wave server
Kune uses Jetty secure termination for stop itself from our
debian/kune.init script. Also you can test while developing how stops kune with something like:
telnet 127.0.0.1 8079 Trying 127.0.0.1... Connected to 127.0.0.1. Escape character is '^]'. devsecret stop Stopped quit
GWT Superdev mode
If you want to use the superdev mode you can:
Run the previous gwt:compile command, run the server (2) and later the superdev launch (3), also you can use
mvn gwt:run-codeserver -P development
Open the code server http://localhost:9876/
Drag&drop the devmode on/off bookmarks to your browser bookmarks toolbar (you need to do this only one time)
open the server http://localhost:8888/
There you can click in your bookmarks on "Dev Mode On" and compile if you do some changes in your java code.
In chrome, for debugging and logs
Launch Chrome Developer Tools (F12)
For debugging, you need to Enable JS Source Maps in Chrome Developer Tools preferences
Open the Source tab and observe the files, or the Console tab to see the logs
More info about Superdev mode (also a screenshot): http://stackoverflow.com/questions/18330001/super-dev-mode-in-gwt
You can run the server via bin/server.sh (you can also run the server in debug mode, see TROUBLESHOOT or -h for help). This is quite useful to put breakpoints in the server code.
FIXME: the following part (between ) is outdated. Please use as reference the existing "launch" files. <<<< You can create a custom launch also at "Run configuration" (Run > Open Run Dialog) in Eclipse with Project: "kune" with Main class: "com.google.gwt.dev.DevMode" with these program arguments (or similar ones): (OUTDATED) "-noserver -out gwt-out ws?locale=en&log_level=INFO -port 8080" and in the "Classpath User Entries": (OUTDATED) gwt-dev-[linux|mac|windows].jar (Add External Jar and choose it from your gwt installation directory) java - /kune/src/main kune (default classpath)
If you have memory problems running the hosted mode, increase it in VM arguments: (OUTDATED) -Xmx1024M
Some relevant docs for Kune development
See these files in the "kune" directory:
There are also some interesting diagrams, that although they are outdated, they provide a general overview:
kune/artwork/old/kune-arch.png # architecture diagram (outdated)
kune/artwork/old/kune-hibernate-diagram-oct-08.png # db schema (outdated)
kune/artwork/old/kune-diagram-part1-0.1.png # (outdated)
kune/artwork/old/kune-diagram-part2-0.1.png # (outdated)
kune/artwork/old/kune-diagram-part3-0.1.png # (outdated)
NOTE: For an updated db schema, look into the Java classes of package cc.kune.domain. NOTE: You will need to clone the repository https://github.com/comunes/kune-artwork inside kune repository
Languages and frameworks used in Kune development
The 2/3 main parts of Kune are developed in Java: the server code, and the workspace client code.
GWT is the key of our Kune workspace UI. As the GWT team says: «GWT's mission is to radically improve the web experience for users by enabling developers to use existing Java tools to build no-compromise AJAX for any modern browser» and we think they achieved it. You have more info and tutorials of GWT in: http://ourproject.org/moin/Contributors#Google_Web_Toolkit_First_Steps
All the workspace CSS are concatenated and compressed using csstidy (see bin/css-compact-and-tidy.css if you want to know how).
Here there is a list of some notable dependencies of Kune. For a more detailed list of dependencies see the file: kune/pom.xml
In the GWT client code we use Gin, also based in Guice.
For details on how to use it, see the Guice User's Guide.
For db persistence, we use OpenJPA.
We use Guice-Persist and its dynamic finders. That is, Guice + Persistence + easy db query. See: UserFinder.java for a sample of finders.
For content indexing, we use Lucene. We usually use Hibernate Search - Apache Lucene Integration documentation.
Client side (GWT)
Averyone is invited to join the Kune developer community and send patches to the code. If you're looking for something to work on:
Check out the open issues in the Redmine issue tracker: http://redmine.comunes.org/projects/kune
If you want to work on something not listed here, go ahead. You can even add an issue if you like.
We advise you to subscribe to at least the kune-devel kune list: http://kune.cc/#!kune.lists.1226 (you need a kune user)
If you need help, don't hesitate to ask on a kune list: http://kune.cc/#kune.lists
When your patch is ready, put it on the Review Board at http://reviews.comunes.org/ and request code review.
You can submit the patch to the Kune Git repo: https://github.com/comunes/kune
We try to make Kune very usable. Thus, please think like a human and use a human language in the UI messages, not techie (neither Klingon or alien) language ;).
Your mother/father must understand and be capable to use Kune if they are capable of using yahoo/gmail/hotmail email accounts. It he/she is not capable of using Kune, we are not doing well our work, and we must do our UI more usable.
Some relevant links to solve doubts:
We use a lot the MVC pattern in our GWT code.
See our HelloWorldModule class for a simple sample. We used to auto generate some MVC classes with the script bin/generateBasicUIElements.sh:
bin/generateBasicUIElements.sh <packageDirDest> <ClassName>
bin/generateBasicUIElements.sh src/main/java/org/ourproject/kune/workspace/client/options/ GroupOptions
this generates four classes:
GroupOptions (the external interface),
GroupOptionsPresenter (the Presenter with the business logic, the part you must test well),
the GroupOptionsView (the interface to the panel, the UI code),
the GroupOptionsPanel (the UI code, with all the GWT UI stuff).
A we described before we use Guice for IoC.
We use certain Eclipse code preferences for Kune project: dev-utils/kune.cleanup.eclipse.preferences.xml dev-utils/kune.formatter.eclipse.preferences.xml please use them if you want to contribute.
NOTE: In order to import those XML in your Eclipse, follow (tested in Eclipse 3.5, 3.6, 3.7): Window | Preferences | Java | Code Style | Formatter & import selecting the formatter XML file. Go to |Clean Up to import the cleanup XML file.
NOTE: In Window | Preferences | Java | Editor | Save Actions, you can set default formatting and cleaning tasks automatically on save. This guarantees your contributions to be always with the appropriate code style.
We will (try) to follow: http://code.google.com/webtoolkit/makinggwtbetter.html#codestyle
and the code conventions for the JavaTM Programming Language: http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
also we try to be a "Good Java Citizen": http://docs.codehaus.org/display/PICO/Good+Citizen
More than the eclipse code preferences we try to use spaces instead of tabs (for instance in xml, we try to use 2 spaces of identation)
Use of Mylyn in Eclipse
We recommend to use Mylyn (Eclipse plugin) to track the Kune issues. If you do, you should use the Redmine Mylyn Connector from the Redmine-Mylyn update site (adding it as repository for Eclipse and downloading the plugin): http://redmin-mylyncon.sourceforge.net/update-site/N/ You should use it for the Kune Redmine: http://redmine.ourproject.org/ More info: http://www.redmine.org/projects/redmine/wiki/HowTo_Mylyn
Besides it is recommended to use EGit for Mylyn plugin: http://www.javaforge.com/project/EGIT
We recommend and use JUnit (in combination with Mockito as mocking framework) for testing. Besides, it is recommended to define tests frequently in the Kune code, which is organised as follows:
src/main/java: Kune source code
src/test/java: Kune JUnit tests source code
Any test class can be run independently as a JUnit Test. It is recommended to set up tests frequently and test them locally before committing the changes. Besides, there is a ".launch" to run all the "kune tests" locally.
NOTE: For automatic running of tests online, see the next section on Continuous Integration.
Jenkins Continuous Integration Server
We use Jenkins as our continuous integration tool. After each commit, it automatically runs the full collection of JUnit tests. The Jenkins instance is located in: http://ci.comunes.org
See HelloWorld*.java classes for a small sample of how to develop and extend the GWT workspace UI.
Apache Wave (old Google Wave)
Wave Client Development Environment Set Up (if you want to work only in the Apache Wave part): http://www.waveprotocol.org/code/client-development-environment-set-up
David Hearnden recommendations of Wave code development (read in an informal Wave conversation):
"Being written in Java, we strongly recommend following the principles outlined in Effective Java. On top of that, patterns that aid testability (dependency injection, etc) are quite important. But beyond that, I don't know if there are any other patterns or practices that would be universal across the whole thing. The web client and the server run in very different environments, so the appropriate patterns change (e.g., the client-only code doesn't have to worry about thread safety, but should worry about excessive short-lived object creation)."
Docs about Operational Transformations (OT), Wave Model, etc
Running Hosted Mode without Wave webclient
See class WaveClientProvider in Kune (in the short term, we should define this in a .gwt.xml instead of there, but this is a starting point).
When changing the User Interface, you may want quick ways of working with it, without the need to reload every time the whole Kune.
Kune has a small sandbox where some UI elements can be tested quickly without a server. It's a simple GWT app. For running the Sandbox, you should follow these steps:
Import /kune/core/kune-sandbox as a project in Eclipse
Project properties => Google => Web Tookit => Enable "Use Google Web Toolkit" with GWT 2.5.1
In the java source some errors will appear. Allow automatic fixing from "Fix Project Setup", which will add the project "kune" to the Build Path
You should be able to run (without running any server before) src/main/java/cc/kune/sandbox/KuneSandbox.gwt.xml from mouse right click => Run As => Web Application. An URL will be provided, which can be open in a browser (Firefox/Chrome/Chromium) with the GWT plugin.
If it doesn't work, you may Run As => Run Configurations => select Kune_sandbox.html => Classpath tab => Click on any User entry => Advanced button => Add Folder => Add, from the project kune, src/main/java, src/main/resources, src/main/webapp => Run
NOTE: you may need to run "mvn eclipse:eclipse" from the kune-sandbox folder.
If you want to make modifications in the Kune CSS, the following will help:
There is a script bin/css-update.sh that should help updating Kune CSS
Use the extension CSS Reloader or CSS Refresh (both for Firefox and Chrome/Chromium) for refreshing just the CSS of the page (instead of needing to refresh the whole page). Use the shortcut provided by the extension (F9 or CTRL+ALT+R).
Kune maven repo
To upload packages you need to configure in .m2/settings.xml something like:
<?xml version="1.0" encoding="UTF-8"?> <settings> <servers> <server> <id>kune.ourproject.org</id> <username>YOUR_USER_IN_OURPROJECT_ORG</username> </server> </servers> </settings>
also you have to
and access via ssh with that key without problems.
We usually upload new packages to this repo via bin/repopubli.sh
Making a Kune release
do the last commits, change debian version and scripts grep -r CURRENTVERSION-SNAPSHOT src/ debian/ bin/ and change these files with CURRENTVERSION
do a mvn release:prepare
if all it's ok: mvn release:perform
if things goes wrong mvn release:prepare -Dresume=false or even mvn release:clean
When doing a GIT commit, you should always provide an appropriate description of your changes.
After relevant commits, you should also update the Changelog (in "debian/changelog" ) using "dch". You should include there all the comments of the commit. This changelog will be included in the DEB package and tranks a summary of changes between debian package versions.
Also update the ./Changelog using: http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob_plain;f=build-aux/gitlog-to-changelog
perl $PATH-TO-GIT-CHANGELOG/git-to-changelog.pl > ChangeLog
NOTE: If you don't have "dch", install it in Debian/Ubuntu/related: 'apt-get install devscripts'
NOTE: To facilitate this task, add in your local .bashrc (email and full name are samples):
#dh_make DEBEMAIL="email@example.com" DEBFULLNAME="Alice White" export DEBEMAIL DEBFULLNAME
NOTE: When generating a new DEB package => dch -i
Attach the following notices to each source of the program at the begining:
Copyright (C) 2007-2016 Licensed to the Comunes Association (CA) under one or more contributor license agreements (see COPYRIGHT for details). The CA licenses this file to you under the GNU Affero General Public License version 3, (the "License"); you may not use this file except in compliance with the License. This file is part of kune. This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see .
In Java just include the COPYRIGHT-AGPLv3.java header.
Contributor License Agreements
The Comunes Association (CA) desires that all contributors of ideas, code, or documentation to the CA projects complete, sign, and submit (via postal mail or email) an Individual Contributor License Agreement (CLA) (see http://comunes.org/licenses/icla.txt). The purpose of this agreement is to clearly define the terms under which intellectual property has been contributed to the CA and thereby allow us to defend the project should there be a legal dispute regarding the software at some future time. A signed CLA is required to be on file before an individual is given commit rights to an CA project.
For a corporation that has assigned employees to work on an CA project, a Corporate CLA (CCLA) is available (seehttp://comunes.org/licenses/cla-corporate.txt) for contributing intellectual property via the corporation, that may have been assigned as part of an employment agreement. Note that a Corporate CLA does not remove the need for every developer to sign their own CLA as an individual, to cover any of their contributions which are not owned by the corporation signing the CCLA.
CLAs may be submitted by traditional postal mail or by emailing a scan of the signed copy to firstname.lastname@example.org. You can also edit the text document, create a detached gpg signature, and send both the document and the detached signature via email.
Get in touch
Now we use more the #kune.lists
We have the classical mailing lists, mainly two:
kune-devel for all development related topics
kune-commits where the repository sends the commit logs and summaries
However, more and more we are using the Kune.cc lists instead of mailing lists. This minimises email flow, maximises productivity, and encourages the use of our own tool (and thus finding bugs or possible improvements). Thus, you can check out the lists in the #kune group of kune.cc: http://kune.cc/#!kune.lists and in particular, the main development list: http://kune.cc/#!kune.lists.1226
You can freely join the group #kune, and you can also subscribe to any of those lists.
It is recommended to be subscribed to both mailing lists and especially to the Kune.cc development list if you want to participate in the development.