Skip to content

Latest commit

 

History

History
193 lines (145 loc) · 9.38 KB

CONTRIBUTING.adoc

File metadata and controls

193 lines (145 loc) · 9.38 KB

Counterclockwise Contributors Guide

Contributors Guide

If you discover issues, have ideas for improvements or new features, please report them to the issue tracker of the repository or submit a pull request. Please, try to follow these guidelines when you do so.

Issue reporting

  • Check that the issue has not already been reported.

  • Check that the issue has not already been fixed in the latest code (a.k.a. master).

  • Be clear, concise and precise in your description of the problem.

  • Open an issue with a descriptive title and a summary in grammatically correct, complete sentences.

  • Include any relevant code to the issue summary.

  • Follow the Angular JS commit convention https://gist.github.com/stephenparish/9941e89d80e2bc58a153 . We are little bit liberal with the conventions, take inspiration from the CCW commits history to find a good mesure

Pull Requests

  • Discuss the Pull Request on the mailing list to maximize the chances it will be accepted

  • Read how to properly contribute to open source projects on Github

  • Centralize the collected knowledge in a new issue in the issue tracker. Mention the created issue on the mailing list thread.

  • Open a pull request that relates to only one subject with a clear title and description in grammatically correct, complete sentences.

  • Create and Use a topic branch off of the master branch to easily amend the pull request later, if necessary. It is OK to rebase the topic branch on top of the master branch.

  • Respect a 1-1 relation between Topic Branches and Pull Requests.

  • During the review/adapt phase for the Pull Request, append commits to the topic branch, don’t rewrite the history. This will make Reviewers life easier.

  • Once the Pull Request is Reviewed and Accepted, it is OK to squash related commits together before merging, if necessary.

You can see the Github Flow page for a visual version of the workflow: https://guides.github.com/introduction/flow/

Developing within Eclipse

Prerequisites

Install & Configure

Warning
 The Git repository contains submodules in ccw.core/ccw-plugins/. you must clone with the --recursive option

  • Clone CCW Repository with the --recursive option (this is a submodule option, see references below for more on submodules)

  • In Eclipse, import the repository projects (ccw.aggregator, ccw.branding, ccw.core, ccw.core.test, ccw.feature, ccw.parent, ccw.product, doc, paredit.clj)

  • cd into ccw.core and invoke mvn clean verify

    • This will install all CCW dependencies in folder ccw.core/lib/

    • The operation must be be repeated after each update of ccw.core dependencies

Run a Test CCW environment

The following launch configuration files automatically install themselves in the "Run/Debug" Toolbar items as Shortcuts:

  • Counterclockwise Plugin for Debugging the Plugin by launching it in the current PDE Target (shortcut for ccw.core/Counterclockwise Plugin.launch)

  • Counterclockwise Product for Debugging the Standalone Product (shortcut for ccw.core/Counterclockwise Product.launch)

  • Counterclockwise Product Tests for Launching the JUnit (SWTBot) tests (some tests don’t pass in this mode) (shortcut for ccw.core.test/Counterclockwise Product Tests.launch)

From the Command Line

Compile / Test / Package

git clone https://github.com/ccw-ide/ccw
cd ccw

# Clean + compile + unit test + integration test + build updatesite
# + build Windows / Linux / OS X standalone products + build documentation:
mvn clean verify

# Compile + tests but no product(s) built (less time to complete):
# This deactivates the `luna` profile which deactivates the `ccw.product` module
mvn verify -P \!luna

# Same as above, but skipping launching tests:
mvn clean verify -DskipTests

# To only launch tests
mvn clean test

The products will be available in folder ccw.product/target/products

Manage Version Numbers

The script script/set-version.sh updates POMs, MANIFESTs and feature.xml :

# If you want to set version to 0.20.0-SNAPSHOT
$ cd ccw
ccw$ script/set-version.sh 0.20.0-SNAPSHOT

Adding clojure.test based tests

  • Add the test namespace in ccw.core.test/src/clj using the usual namespace structure for folders

  • Add the namespace to the list of namespaces to be tested in the java file ccw.core.test/src/java/ccw/core/ClojureTests.java

Make CCW depend on a new feature

Version Release Checklist

  • Determine the new version number

  • Update the Changelog note

  • Mark the issues as Fixed

  • Determine the versions of the dependencies to use

  • if required, cut new versions for these

    • ccw-server for instance

  • Upgrade the version numbers

  • Commit and tag

    # Edit Changelog then...
    ./script/set-number 3.4.9.STABLE001
    git commit -a -m"chore(mvn): Version 3.4.9.STABLE001"
    git tag "v3.4.9.STABLE001"

  • Push, let Jenkins build

    git push ccw-ide master --tags
    # Edit Changelog then...
    ./script/set-number 3.4.10-SNAPSHOT
    git commit -a -m"chore(mvn): Upgrade version to 3.4.10-SNAPSHOT"

How To …​

Add a new user plugin as a submodule

  • First clone the plugin as a submodule in the right directory

    cd ccw.core/ccw-plugins/
    git submodule add https://github.com/ccw-ide/ccw-plugin-xxx.git

  • Then open ccw.core/plugin.xml in Eclipse

    • In the Runtime Tab, add ccw-plugins/ccw-plugin-xxx to the classpath

    • In the Build Tab, in the Binary Build group, ensure that ccw-plugins/ccw-plugin-xxx is checked (everything inside ccw-plugins should be checked)

References

Eclipse development links

IResource / IFile / IFolder / IProject

SWT StyledText Widget

Eclipse Launcher Framework