| <div class="titleBig">Getting involved</div> | |
| <div class="section-content"> | |
| <p> | |
| Everyone is invited to get involved with the EMFStore project. | |
| Before you plan any kind of contribution, it is a good idea to | |
| contact the <a href="contact.html" target="_blank">project team</a>. | |
| </p> | |
| <ul class="no-bullets"> | |
| <li><em>Writing bug reports</em> | |
| <p> | |
| Please provide a short and concise explanation of the problem and a | |
| snippet to reproduce the issue, ideally a JUnit test case that | |
| outlines the expected behavior. You are also invited to enter feature requests. | |
| Please use | |
| <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EMFStore" | |
| target="_blank"> | |
| Bugzilla | |
| </a> to report bugs and feature requests. | |
| </p></li> | |
| <li id="commitGuidelines"><em>Commit Message Guidelines</em> | |
| <p> | |
| We have the following commit message template: | |
| <pre> | |
| (Bug <Bug ID> - <Bug Title>) | (TCI - <Fix>) | |
| <Commit Description>? | |
| Change-Id: <Generated Gerrit Change ID> | |
| Signed-off-by: <sign off name and email> | |
| </pre> | |
| <strong>Instructions (Please continue READING):</strong> | |
| <ul> | |
| <li><em>TCI commits</em>: For trivial code changes please use a TCI commit message. See list below for examples. If in doubt please discuss with reviewer.</li> | |
| <li><em>Normal Commits</em>: For all other commits use a commit message starting with 'Bug'. Bug reports with Proper Titles: Before using a Bug title for a commit, committer must update the Bug title to a reasonable and descriptive title for the task they have worked on</li> | |
| <li><em>Commit Description</em>: Additionally to the title, the commit message can describe briefly (2-3 sentences) how this commit fixes the bug from a technical perspective</li> | |
| <li><em>Multiple Commits for same bug</em>: Of course you may use the same bug and therefore bug title for multiple commits and their message, in this case please provide a unique description</li> | |
| <li><em>Reviewers responsibility</em>: The reviewer is responsible also for checking that the bug title is descriptive and reflects the committed change and that the description if any reflects the technical change</li> | |
| </ul> | |
| <strong>TCI message examples: </strong> | |
| <ul> | |
| <li>JavaDoc</li> | |
| <li>NPE</li> | |
| <li>Version Update of manifest and pom</li> | |
| <li>anonymous to inner class Conversion</li> | |
| <li>Renaming local vars, e.g. because of typos</li> | |
| <li>Externalizing strings</li> | |
| </ul> | |
| </p></li> | |
| <li><em>Use Gerrit to contribute to EMFStore</em> | |
| <p> | |
| We use | |
| <a href="http://wiki.eclipse.org/Gerrit" | |
| target="_blank"> | |
| Gerrit | |
| </a> code review so you can easily contribute to EMFStore and get a review for your | |
| changes. Please make sure that all your commits refer to a | |
| <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EMFStore" | |
| target="_blank"> | |
| Bugzilla | |
| </a> Bug. | |
| </p></li> | |
| <li><em>Providing a patch to fix a bug or add a feature</em> | |
| <p> | |
| Please attach your patch to the bug report in question or create a new report using | |
| <a href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=EMFStore" | |
| target="_blank"> | |
| Bugzilla</a>. | |
| </p></li> | |
| <li><em>Contribute documentation</em> | |
| <p> | |
| If you found something that is not documented, please share | |
| your knowledge with other users. Please <a | |
| href="contact.html">contact | |
| us</a>, to find the appropriate place to add your documentation. | |
| </p></li> | |
| </ul> | |
| <h4>How to setup your IDE</h4> | |
| <ul class="no-bullets"> | |
| <li><b>Step 1: Download and install Eclipse</b> | |
| <p> | |
| Please use the Eclipse Modeling Tools from the <a href="http://www.eclipse.org/downloads" target="_blank">Eclipse downloads</a> section. | |
| </p></li> | |
| <li><b>Step 2: Additional Plug-Ins and Settings</b> | |
| <p> | |
| Install Checkstyle Plug-In from either the Marketplace | |
| (Help->Eclipse Marketplace...) or from the | |
| <a href="http://eclipse-cs.sf.net/update/" | |
| target="_blank"> | |
| Checkstyle Updatesite | |
| </a>. All projects have a project specific checkstyle setting, so no need to set this. | |
| </p> | |
| <p>Set the API baseline to the latest release. For this you need to download the release as a zip file and create a new baseline using Preferences => Plug-In Development => API Baselines.</p> | |
| <p>All bundle contain bundle specific settings for formater, warnings and so on, so you don't need to set them. If you create a new bundle, please copy the .settings folder from an existing one</p> | |
| <p>Install the "API Tools Execution Environment Descriptions" from the Eclipse Project Updates site. | |
| </p></li> | |
| <li><b>Step 3: Check-out the source via git</b> | |
| <p> | |
| If you want to use git as an anonymous user (read-only) please use the following URLs: | |
| </p> | |
| <p> | |
| <code>https://git.eclipse.org/gitroot/emf-store/org.eclipse.emf.emfstore.core.git</code> | |
| </p> | |
| <p> | |
| If you want to use Gerrit please use the following URL: | |
| </p> | |
| <p> | |
| <code>ssh://eclipse-id@git.eclipse.org:29418/emf-store/org.eclipse.emf.emfstore.core.git</code> | |
| </p> | |
| <p> | |
| If you want to use git as a committer, please use the following URL: | |
| </p> | |
| <p> | |
| <code>ssh://committer_id@git.eclipse.org/gitroot/emf-store/org.eclipse.emf.emfstore.core.git</code> | |
| </p> | |
| <p> | |
| Select the "develop" branch. The develop branch is used for development while the master branch contains tagged release | |
| versions of EMFStore that must not be changed once they have been released. | |
| Press "Select all" and proceed with the import. | |
| </p> | |
| <p> | |
| Please refer to | |
| <a | |
| href="http://wiki.eclipse.org/EGit/User_Guide/Remote#Cloning_remote_Repositories" | |
| target="_blank"> | |
| this tutorial | |
| </a> | |
| to clone git repositories. Now, you can import the | |
| projects from the cloned git repository. See | |
| <a href="http://wiki.eclipse.org/ImportGitProjects" | |
| target="_blank"> | |
| here | |
| </a> to learn how to | |
| import projects from a git repository. | |
| </p></li> | |
| <li><b>Step 4: How to import and set the target</b> | |
| <p> | |
| Once you have checked out the branch, you will see the following directory structure consisting of four directories: | |
| <code>bundles</code>, <code>features</code>, <code>tests</code> and <code>releng</code>. | |
| Each one of these directories serves a specific purpose: | |
| </p> | |
| <ul> | |
| <li><code>bundles</code> contains all EMFStore plugins</li> | |
| <li><code>features</code> contains all features</li> | |
| <li><code>tests</code> contains all tests</li> | |
| <li><code>releng</code> contains all release enginnering-specific assets</li> | |
| </ul> | |
| <p> | |
| Now locate and open the <em>emfstore.target</em> file in the <em>_target</em> bundle imported from the repository. | |
| When it is resolved, set the target definition as the target platform. | |
| Please note that the resolution of the target platform may take some time the first time it is set. | |
| </p> | |
| </li> | |
| <li><b>Step 5: Configure your workspace</b> | |
| <ul> | |
| <li> | |
| <b>Set the API baseline</b> | |
| <p> | |
| To help detecting source changes that would break the API of EMFStore, we use the API tools provided by Eclipse. | |
| Therefore you'll need to set up an API baseline which Eclipse will compare your current workspace against. | |
| </p> | |
| <p> | |
| To set up an API baseline, download the latest EMFStore release and open up your Preferences. Navigate to | |
| <em>Plug-in Development > API Baselines</em>. Select "<strong>Add Baseline</strong>", name your baseline meaningful | |
| and click "<strong>Browse</strong>" to select the root folder of your downloaded EMFStore SDK. Click <strong>OK</strong> and once the | |
| baseline is initialized, click <strong>Finish</strong>. | |
| </p> | |
| </li> | |
| <li> | |
| <b>Set encoding and line delimiter</b> | |
| <p> | |
| Navigate to <em>General > Workspace</em> and and set the <em>Text file encoding</em> to <strong>UTF-8</strong> and the | |
| <em>New text file line delimiter</em> to <strong>Unix</strong>. | |
| <img src="public/images/ws-preferences.png"/> | |
| </p> | |
| </li> | |
| </ul> | |
| </li> | |
| <li><b>Step 6: Java 1.5 compatibility</b> | |
| <p> | |
| As we want to be 1.5 compatible, you need to install the "API Tools Execution Environment Descriptions" from the Eclipse Project Updates site (already available as an update site) in Eclipse. | |
| If you need to create a new project, please ensure that: | |
| <ul> | |
| <li>All execution environments are set to Java 1.5</li> | |
| <li>The <em>API Errors/Warnings</em> project specific setting <em>Reference not defined in specified execution environment</em> is set to <strong>Error</strong></li> | |
| </ul> | |
| </p> | |
| </li> | |
| <li><b>Step 7: Start EMFStore</b> | |
| <p> | |
| As a reference UI, we use the User Interface provided by EMF Client Platform (EMFCP). | |
| For testing purposes, you can use <a href="http://download.eclipse.org/emfclient/example/examplemodel.zip">this | |
| example model</a>. Import it into your EMFCP workspace. | |
| </p> | |
| <p> | |
| Start the model with EMFCP by creating a run configuration. | |
| This run configuration will automatically also contain the example model from your developer workspace. | |
| To create a run configuration, select the Eclipse menu <em>Run → Run Configurations</em>. | |
| </p> | |
| <p> | |
| Create a new run configuration and run the application <em>org.eclipse.emf.ecp.application.e3.application</em>, | |
| as shown in the following screenshot. | |
| </p> | |
| <p> | |
| <img src="public/images/runningconfig.jpg"/> | |
| </p> | |
| <p> | |
| Now you can start your application; it should present you with an empty ECP workbench containing the example model. | |
| </p> | |
| </li> | |
| </ul> | |
| <h4>Framework Developer Documentation</h4> | |
| <p>See the <a class="link" href="dev-guidelines.html">developer documentation</a>.</p> | |
| <h4>Branching scheme</h4> | |
| <p>In our GIT Repositories we are using the branching scheme described <a class="link" href="http://nvie.com/posts/a-successful-git-branching-model/">here</a>.</p> | |
| <p>We have a master branch containing the last release. A development branch containing the current development state and (hopefully) some feature branches containing new feature developments.</p> | |
| <p>So if you are a developer please commit on the develop branch in the future. If you develop a new feature please open a feature branch and merge it back to the develop branch when your feature is finished. Don't commit on the master branch as it should only contain stable release versions merged there by the release engineer.</p> | |
| <img alt="Branching Scheme" src="public/images/branchStrategy.png" height="452" width="355"/> | |
| <h4>Profiling and Performance Debugging</h4> | |
| YourKit is kindly supporting the EMFStore open source project with its full-featured | |
| <a target="_blank" href="http://www.yourkit.com/java/profiler/index.jsp">YourKit Java Profiler</a>, which helped us to greatly improve EMFStore. | |
| </div> |