Contributing to Echo

Chris May edited this page Jun 14, 2013 · 5 revisions

Git and GitHub are a great tool for collaboratively working on projects. Properly used it allows you to easily maintain local patches and rework them until they get included in upstream or even maintain a local variants which mixes official with custom modifications.

Starting points

Some short starting notes:

  • http://help.github.com/ offers extensive help about how to get started with Git and GitHub in general
  • Refer to the chapter 'Submitting patches' on details
  • Ask in the community before doing major work, to ensure your patch can be accepted timely.

Building Echo


Echo can be built by running

ant dist

which will automatically fetch the required dependencies JAR using Maven.

IDE

As IDE we recommend using IntelliJ IDEA. The project folder already contains the project definition which allows you to directly open the project in IDEA.

Note that you must run ant at least once before opening the project to make sure the required libraries are fetched from Maven central an present in the lib directory.

IntelliJ IDEA

On the first run you have to register & select a installed JDK and choose a default compilation output folder (choose a new empty folder 'build' in the project to avoid errors about missing classes on running the unit tests). Test your setup by executing the "All JUnit Tests" target.

The free community edition is sufficient, though the ultimate edition offers significant additional comfort (i.e. inline JavaScript debugging).

Eclipse

The current development branch also contains an unofficially maintained Eclipse project. On any issues please contact @chrismay2.

Submitting patches

Working with branches

Please split your development separate branches per hotfix/feature and open individual pull requests, so each feature can be reviewed individually.

  • Currently the official repository maintains the following branches:
    • master which is an experimental, next major version branch and
    • stable-xxx which adresses the current stable release series
  • Please choose the right starting point for your patch. Ideally you branch of v3.0.0 or stable-3.0.x for minor/bugfix/maintenance changes. For any experimental/bleeding-edge change master can be used as well.

    git checkout v3.0.0 -b feature/my-newfeature

Code style

We are very conservative regarding code quality. Your submission should

  • Build and run without any problems (including ant test)
  • Introduce no trailing spaces, mixed line-endings, use only spaces (no tabs)
  • Every new member should be well documented including
    • JavaDoc for every new public Java-Symbol and
    • JsDoc for every new JavaScript Symbol/API