View source for Capra/Contributing

We welcome all contributions from the community to Capra. In particular, we are always interested in additional artifact handlers that allow Capra to use more artifacts and the sources and targets of traceability links. If you are interested in helping out by fixing bugs or want to see what other things we have planned, please check our [https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Capra Bugzilla].

= Becoming a member of the Eclipse Community =

In order to use the Eclipse development infrastructure and to contribute to Capra (and other Eclipse projects), it is necessary to create an [https://dev.eclipse.org/site_login/createaccount.php Eclipse account]. With this account, you will be able to log in to the different services (such as [https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Capra Bugzilla], the [https://wiki.eclipse.org/Main_Page Eclipse Wiki], or [https://hudson.eclipse.org/capra/ Hudson]) and push code changes to [https://git.eclipse.org/r/#/admin/projects/capra/org.eclipse.capra Gerrit].

After you have created the account, you need to sign the [https://eclipse.org/legal/#CommitterAgreements Eclipse Committer Agreement] (ECA). Depending on whether you work on your own time or for a company, different conditions apply. Please familiarise yourself with the legal issues, ask your employer for help if required, and then sign the ECA [https://dev.eclipse.org/site_login/myaccount.php#open_tab_cla here].

= Setting up your development environment =

The easiest way to set up everything you need to develop Capra is to use the Eclipse Installer and our dedicated setup file. Please follow the instructions on the [[Capra]] wiki page.

= Cloning from Git/Gerrit =

The easiest way to contribute to Eclipse Capra is to use the Git/Gerrit repository directly. You can copy the SSH or HTTPS links from the [https://git.eclipse.org/r/#/admin/projects/capra/org.eclipse.capra Capra Gerrit page]. This will allow you to push your changes directly to Gerrit where the project committers can review them before adding them to the codebase.

To create a new clone with EGit:
* Switch to the Git Perspective, select Clone a Git Repository (icon with a blue arrow), then select Gerrit and follow the wizard.
* Import all projects into your work space
* Create a branch based on the <code>develop</code> branch. All development should be based on this branch, following the [http://nvie.com/posts/a-successful-git-branching-model/ GitFlow] approach. Your local changes should go into your own branch. We suggest to use the format <code><username>/feature/<feature-name></code>. Instead of `feature`, other identifiers such as <code>fix</code> can be used.
<br/>

If you have already cloned the Eclipse Capra Git repository (e.g., because you used the Eclipse Installer to set up your development environment), you can add Gerrit as a remote to your already cloned repo:
* If you want to add Gerrit as an additional remote, execute <code>git remote add gerrit <gerrit-repo></code>. You can then push to Gerrit by using <code>git push gerrit HEAD:refs/for/develop</code>.
* If you want to override the standard remote, execute <code>git remote set-url origin <gerrit-repo></code>.

If you have created a branch as described above, a simple <code>git push</code> will push your commit to that branch without going through the Gerrit review process. If you would like to submit your commit for review, please follow the instructions below.

= Sharing your Idea with the Community =

We keep track of the features for Capra in our [https://bugs.eclipse.org/bugs/describecomponents.cgi?product=Capra Bugzilla]. If you plan to contribute your own features, please open a bug in the correct component there. The bug summary should contain the "[feature]" keyword so we know that this is not indeed a bug report. Please provide a short summary and a description of what you are doing. Use the comments of the bug to describe your progress. Other members of the community might engage you for discussions, so please take their opinions into account and react to their suggestions and feedback.

= Building and Testing =

Capra uses Maven/Tycho. To check if your changes work, run maven in the root folder:

 mvn clean verify

This will create binaries for Capra and run all tests. Code should only be committed if all tests passed! Since all commits will be build by our [https://hudson.eclipse.org/capra/ Hudson instance], which in turn uses Maven to build Capra, a failed Maven run on your machine is a good indication that your commit will not be verified.

Please note that building Eclipse Capra currently requires the use of JRE 8. Please make sure that Maven uses JRE 8 by setting the <code>JAVA_HOME</code> environment variable appropriately.

To run Capra from within Eclipse, see the instructions on the [[Capra]] wiki page.

= Handling dependencies =

All dependencies introduced by new commits need to be cleared through the [https://www.eclipse.org/projects/dev_process/ip-process-in-cartoons.php Eclipse IP process]. That means that we need to file a Contribution Questionnaire (CQ) for each new dependency introduced. Since only committers have the right to do so, other contributors need to let us know that a new dependency has been introduced and allow us to initiate the IP process. The only exception are dependencies to bundles in the org.eclipse.* namespace. These can be used without a review. 

The review process is usually not difficult, unless there is no obvious license or the code is licensed under a [https://en.wikipedia.org/wiki/Copyleft copyleft licenses] such as GPL. Dependencies with such licenses will not be accepted by the review process, so don't even bother trying and use another library instead.

There are some things that you can do to make this process easier:

# Check that the dependency that you want to use is part of one of the [http://download.eclipse.org/tools/orbit/downloads/drops/ Orbit drops]. Everything in Orbit has been pre-cleared and the procedure is much easier for us. You might not find the latest version of the bundle you want to use there, but usually there is at least one that contains the most important functionality. If you need a more recent version, it is still good to know that there is an existing Orbit version since that also reduces the effort required to review the dependency.
# Create a bug in the [https://bugs.eclipse.org/bugs/buglist.cgi?component=Development&list_id=16004364&product=Capra&resolution=--- Development] component of Capra in Bugzilla. Preface the summary of the bug with the "[dependency]" keyword and use the bundle name and version. An example is "[Dependency] com.google.inject v3.0.0". 
# In the description of the bug, mention the plugin this dependency is going to be used in and link to the appropriate Orbit drop (if applicable).
# Create a ZIP or JAR file that contains only the sourcecode (including any text files, xml files, etc.) of the dependency, but no other JARs or binaries. Usually, the source distribution of the bundle you want to use should do, but check that it does not contain any nested dependencies. Attach the archive to the bug.
# One of the project committers will take the bug and file the CQ. The link to the CQ will be posted in the bug.
# As soon as the CQ has been approved, the bug will be resolved. You can push your code to Gerrit as soon as '''all''' dependency issues have been resolved.

== Adding dependencies to target platform and pom.xml ==

All dependencies need to be added to the target platforms. Please add them to the <code>*.tpd</code> files and regenerate the target platform files. In case the dependency uses an external update site, this update site also has to be added as an [https://www.eclipse.org/lists/tycho-user/msg07244.html associate site] to the <code>pom.xml</code> file in the <code>releng/org.eclipse.capra.releng.p2update</code> bundle.

= Before committing =

Please make sure that '''all''' points in the following checklist are fulfilled before committing your work to a Capra repository:

* The code is formatted according to the built-in Eclipse code formatting rules.
* All classes and all public methods are documented.
* Each source code file has a copyright header (see below).
* The imports are organised.
* All open bugs for newly introduced dependencies have been resolved (see above).

Organisation of imports and code formatting can be automated by selecting them as save actions for the Java editor in the Eclipse preferences.

= Adding new source files =

It is important to maintain the correct copyright messages, indicating the contributors of each file and that it is covered by the EPL. You can use automation to insert a correct copyright header.

Install the [https://wiki.eclipse.org/Development_Resources/How_to_Use_Eclipse_Copyright_Tool Eclipse Releng Tools]. They contain the copyright tool. Use the following copyright header:


  Copyright (c) ${date} Chalmers | University of Gothenburg, rt-labs and others.
  All rights reserved. This program and the accompanying materials
  are made available under the terms of the Eclipse Public License v2.0
  which accompanies this distribution, and is available at
  http://www.eclipse.org/legal/epl-v20.html
   
  SPDX-License-Identifier: EPL-2.0
   
  Contributors:
     Chalmers | University of Gothenburg and rt-labs - initial API and implementation and/or initial documentation
     Chalmers | University of Gothenburg - additional features, updated API

The Contributors entry can be replaced with the appropriate names. Use "Fix copyrights" from the context menu to add the copyrights to all relevant files in a project or folder.

= Pushing changes to Gerrit =

If all pre-requisites listed above are fulfilled, the code can be pushed to Gerrit. Please note that Gerrit combines several commits into one change that will show up using the commit message of the last commit. Make sure that this commit message actually describes the changes you are pushing. Optionally, you can squash all commits into one before pushing to Gerrit.

These are the steps to push a change to Gerrit:

* Make sure that the code compiles and the tests run through by running <code>mvn clean verify</code>
* (Optional) Squash all local commits into one
* Make sure your commit message describes the feature you contribute
* Sign-off the commit: add a Signed-off-by footer to the commit message. If this is missing, Gerrit will not accept your push!
* Before pushing, make sure you pull and rebase from the remote branch so that you get all recent changes (in case there any). You can configure your repositories to always use "pull --rebase" by running the following command on your terminal <code>git config --global --bool pull.rebase true</code>
* Push your changes to Gerrit. You can either do this through Eclipse or manually on the command line with a command like this: <code>git push ssh://<username>@git.eclipse.org:29418/capra/org.eclipse.capra.git HEAD:refs/for/develop</code> or <code>git push gerrit HEAD:refs/for/develop</code> if you followed the instructions above.

Please note that it is important to use the <code>HEAD:refs/for/develop</code> addition which indicates that the push is to Gerrit (<code>refs/for/</code>) and which branch the changes should be merged to (<code>develop</code>).

The Sign-off needs to be in the footer of the commit message, i.e., separated from the commit message by a new line and in the same block.

Once your change has been pushed to Gerrit, Jenkins will try to build your code. If Jenkins was successful, one of the committers in the project will review the change. You will be notified about the progress by email, using the email address you used in the Signed-off-by message. If your change is accepted, it will be merged into one of the branches in the main Git repository. If there are comments or Jenkins fails to build the code, you need to make the necessary changes, amend your commit, and push again by following this procedure:

* Make the necessary local changes
* Amend last commit via <code>git commit --amend</code>
* Add Gerrit Change-Id to your commit message (if it's not there yet)

Change-Id and Sign-off both need to be in the footer.

== Creating your own branch ==

Committers are encouraged to push changes to new branches. To enable review via Gerrit, it is necessary to first create a remote tracking branch (without a commit before pushing. For this purpose, follow this sequence of commands:

 git fetch
 git checkout develop
 git push origin HEAD:<username>/feature/<branchname>
 git checkout <username>/feature/<branchname>
 [Commit your changes here. Each commit will result in a separate Gerrit change.]
 git push ssh://<username>@git.eclipse.org:29418/capra/org.eclipse.capra.git HEAD:refs/for/<username>/feature/<branchname>

== Configuring Git correctly ==

With the introduction of Gerrit 3.1, you might now receive a warning when pushing: <code>warning: pushing without Change-Id is deprecated</code>

The solution to this issue is described [https://stackoverflow.com/questions/8845658/gerrit-error-when-change-id-in-commit-messages-are-missing here]. In short, you need to create a hook that adds a change ID whenever you push to Gerrit. The easiest way to accomplish this is to run <code>scp -p -P 29418 <username>@git.eclipse.org:hooks/commit-msg .git/hooks/</code> in your local repository's main directory.

= Additional information =

More information about contributing code via Gerrit and how to use the Eclipse Git repositories can be found here:

* A good overview of a workflow with Gerrit/Bugzilla/Hudson is provided [https://www.eclipse.org/community/eclipse_newsletter/2013/september/article4.php here]
* [[Gerrit]]
* [[Development_Resources/Contributing_via_Git]]
* [[Stardust/Contributing_via_Gerrit]]
* [[CDT/contributing]]

[[Category:Capra]]