View source for BPMN2-Modeler/DeveloperTutorials/HowToStartContributing

If you want to contribute to this project, you can find a short tutorial below how to start:


== Report a Bug == 

Frist of all take a look into the [https://bugs.eclipse.org/bugs/describecomponents.cgi?product=BPMN2Modeler Issue Tracker] of the BPMN2 Modeler project. There you can find current issues we are working on and we are pleased if you will help us here.

You can also report a new issue [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=BPMN2Modeler here].


== Clone the Git Repository ==

If you want to debug the BPMN2 Modeler project or to start your own contribution you can checkout the latest development branch from the Git source code repository. The BPMN2 Modeler project is based on Gerrit which makes it easy to submit contributions for a review process.

To clone the repository use the following Git repository URL:

 ssh://[USER ID]@git.eclipse.org:29418/bpmn2-modeler/org.eclipse.bpmn2-modeler.git

where [USER ID] is your committer user id.

When you clone the repository, you will find a lot of branches. In most cases it is sufficient to checkout only the master branch or the branch pointing to one of the Eclipse major releases you are working on (e.g. photon, neon,...)
[[Image:BPMN2Modeler_DeveloperTutorials_HowToStartContributing-01.png|center|thumb|500px|BPMN2Modeler_DeveloperTutorials_HowToStartContributing-01]]

'''Note:''' The master branch contains the release for the next Eclipse version. For the current Eclipse IDE checkout the corresponding branch (e.g. neon).

You may also need to check/update your .git/config file with the following:

      fetch = +refs/heads/*:refs/remotes/origin/*
      fetch = refs/notes/*:refs/notes/*
      push = HEAD:refs/for/master

And that should be it.

== Import the BPMN2 Modeler project into your Workspace ==
Now you can import the BPMN2 Modeler project into your workspace

Choose "Import -> Maven ->  existing maven project"

[[Image:BPMN2Modeler_DeveloperTutorials_HowToStartContributing-02.png|center|thumb|500px
]]

and select your local repository location (e.g.  ~/git/org.eclipse.bpmn2-modeler/)

[[Image:BPMN2Modeler_DeveloperTutorials_HowToStartContributing-03.png|center|thumb|500px]]

In most cases the following plug-in modules of the BPMN2-Modeler are sufficient:

 * org.eclipse.bpmn2.modeler
 * org.eclipse.bpmn2.modeler.core
 * org.eclipse.bpmn2.modeler.ui

Next you can open the plugin.xml file from the subproject  'org.eclipse.bpmn2.modeler.core' project and start the plugin directly from your IDE. You can also launch the plugin in the debug mode form here:

[[Image:BPMN2Modeler_DeveloperTutorials_HowToStartContributing-04.png|center|thumb|500px
]]


== Commit your Changes via Gerrit ==

As far as committing changes to the Gerrit git repo, you should be able to just push to gerrit, and this will create a change record for review. You need to create a eclipse account if you have not done yet. Please have a look at the [https://www.eclipse.org/projects/handbook/#project-resources-and-services Eclipse Project Handbook] and the  [https://wiki.eclipse.org/Gerrit Gerrit Wiki Page] if you run into problems. 

In short the process of a pushing a change into the master branch has the following steps

# Create a Bugzilla Issue if not yet done
# Test your local changes with a local maven build 
# Push your changes into Gerrit
# Wait until a committer has reviewed, verified and submitted your change in Gerrit
# Pull the merged changes again into your local git repo. 

=== The Commit ===

To commit your changes the commit message have to be in the right format. 
First of all make sure hat you have the bugzilla issue id. If you not yet have an existing issue ID in [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=BPMN2Modeler Bugzilla], start creating a new issue first.

The commit message has the following format

 Bug 516607 
 
 details about your fix...Participant
 
 Change-Id: I0000000000000000000000000000000000000000
 Signed-off-by: Ralph Soika <ralph.soika@imixs.com>

The 'Signed-off-by' message can be generated automatically by Eclipse when you press the 'Add-singed-off-by' icon:

[[Image:BPMN2Modeler_DeveloperTutorials_HowToStartContributing-05.png|center|thumb|500px
]]

If you start the first line of the commit message with Bug 12345 or [12345], than the bug will be linked automatically with the commit in Gerrit (see also [http://www.eclipse.org/projects/handbook/#resources-commit here]).

The Change-ID can be ignored. This ID is generated automatically during the commit!

You will find more information about the Gerrit Commit Message [https://git.eclipse.org/r/Documentation/user-changeid.html here].

After you have pushed your changes, you can track the review process via the Gerrit Link listed in your git message or bugzilla issue.

=== Verify and Submit your Changes in Gerrit ===

After you pushed your changes into Gerrit it's time to review, verify and submit your changes. This can be done by an committer of the BPMN2-Modeler Project only. 

First post your code review comment:

[[Image:BPMN2Modeler_DeveloperTutorials_HowToStartContributing_gerrit_001.png|center|thumb|500px
]]

Next verify the commit:

[[Image:BPMN2Modeler_DeveloperTutorials_HowToStartContributing_gerrit_002.png|center|thumb|500px
]]

Finally submit the commit so it will be merged into the master branche

[[Image:BPMN2Modeler_DeveloperTutorials_HowToStartContributing_gerrit_003.png|center|thumb|500px
]]


After this you can pull your changes again from the git repo. The Bug report in Bugzilla will be updated and a (Nightly Build [https://ci.eclipse.org/bpmn2/job/bpmn2-modeler.nightly/]) will be started automatically.

== The Build Process ==
To start the build process of Eclipse BPMN2 Modeler plugin run the maven install goal on the project root:

 $ mvn clean install

you need to specify a eclipse release as defined in the profiles of the pom.xml. See the following example to build the project for the current Eclipse platform release:

 $ mvn clean install -Pplatform-2019-06 -Dcbi.jarsigner.skip=true

Note: the profiles are defined in the file /parent/pom.xml 

The update site is created at the ~/target/repository folder of the update site module.

=== Nightly Builds ===

Nightly builds represent the last successful build from the master branch. You can install these version from the following update site:

http://download.eclipse.org/bpmn2-modeler/updates/nightly/oxygen

Changes merged into the master branch will be automatically build from the Eclipse CI platform as a 'nightly build'. You can check the build process [https://hudson.eclipse.org/bpmn2/job/bpmn2-modeler.nightly/ here].