Skip to content

Latest commit

 

History

History
765 lines (510 loc) · 34.5 KB

DEV-GUIDE.md

File metadata and controls

765 lines (510 loc) · 34.5 KB
Raw

Table of Contents

KUNE DEVELOPER'S GUIDE

Summary of development resources

Development Environment

Preliminars

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.

Initial steps

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:

http://ourproject.org/moin/Contributors#Recommended_Firefox_Extensions

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

http://www.eclipse.org/downloads/

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:

(*): 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

Eclipse configuration

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):

mvn eclipse:eclipse

IMPORTANT: (*)

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.

UTF 8

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

  1. From the Eclipse Marketplace:

    • The FindBugs plugin (looks for bug patterns)

    • Mylyn (task-focused development)

  2. 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)

  3. From the repository http://pmd.sourceforge.net/eclipse

    • The PMD Eclipse plugin (scans the code looking for potential problems).

  4. 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)

  5. Also maybe some other plugins are interesting such as:

    • Quick Junit

    • JUnitHelper

    • 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

Install Kune

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:

bin/deploy_gwt.sh

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:

  1. 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

  2. Open the code server http://localhost:9876/

  3. Drag&drop the devmode on/off bookmarks to your browser bookmarks toolbar (you need to do this only one time)

  4. open the server http://localhost:8888/

  5. 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

Optionally

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

Java

The 2/3 main parts of Kune are developed in Java: the server code, and the workspace client code.

GWT

GWT is used for the client workspace. See the Getting Started.

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

HTML/CSS/JavaScript

All the HTML/JavaScript code of the client workspace is generated from the Java code using GWT. We use some minimal HTML/CSS (see kune.css, doc.css, workspace.css, Kune.html) plus the generated JavaScript (compiling the java code with GWT).

All the workspace CSS are concatenated and compressed using csstidy (see bin/css-compact-and-tidy.css if you want to know how).

Notable dependencies

Here there is a list of some notable dependencies of Kune. For a more detailed list of dependencies see the file: kune/pom.xml

Server side

Guice

Guice is used in the server code for IoC. As they describe «Put simply, Guice alleviates the need for factories and the use of new in your Java code. Think of Guice's @Inject as the new new.».

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.

Apache OpenJPA

For db persistence, we use OpenJPA.

Guice Persist

We use Guice-Persist and its dynamic finders. That is, Guice + Persistence + easy db query. See: UserFinder.java for a sample of finders.

Lucene

For content indexing, we use Lucene. We usually use Hibernate Search - Apache Lucene Integration documentation.

Client side (GWT)

GIN

Gin is the IoC library that we use for GWT. For more documentation see the Gin tutorial. See also our Guice section above.

Emite

emite is our xmpp extensible library and client. See the wiki for more documentation about emite. It's a module totally independent of Kune, so you can also use emite in your website or project.

We use these forks: https://github.com/comunes/emite/ https://github.com/comunes/hablar/

UI Binder

We use UI Binder for GWT Widgets. Also we use GWT Design Eclipse Plugin for developing these widgets.

ext-gwt/gxt

gxt is used for other parts of our GWT UI (like window dialogs, grids, etc). See the gxt explorer for sample codes and gxt docs.

Coding

Averyone is invited to join the Kune developer community and send patches to the code. If you're looking for something to work on:

Some recommendations

Usability

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:

Designs patterns

MVC

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>

for instance:

 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).

IoC

A we described before we use Guice for IoC.

Code preferences

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

It is recommended that you use the PMD plugin in eclipse: http://pmd.sourceforge.net/ http://pmd.sourceforge.net/eclipse/

Identation:

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

Testing

JUnit tests

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

You can get notifications of our builds via our Telegran channel: https://t.me/comunes_builds. More info: https://github.com/jenkinsci/build-notifications-plugin

Code samples

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

http://www.codecommit.com/blog/java/understanding-and-applying-operational-transformation Wave Model Deep Dive: http://www.youtube.com/watch?v=6ZqpeFydq4A

Or for a list: http://www.youtube.com/user/GoogleDevelopers/search?query=Wave

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).

UI dev

When changing the User Interface, you may want quick ways of working with it, without the need to reload every time the whole Kune.

Sandbox

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.

CSS

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

ssh-copy-id YOUR_USER_IN_OURPROJECT_ORG@ourproject.org

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

Changelog

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="alice@domain.dom"
 DEBFULLNAME="Alice White"
 export DEBEMAIL DEBFULLNAME

NOTE: When generating a new DEB package => dch -i

License

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 comunes@ourproject.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

Mailing lists

Now we use more the #kune.lists

We have the classical mailing lists, mainly two:

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.

Twitter/Identica

You can follow @kuneproject in Twitter and Identica.