|
|
| (3 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | = Introduction =
| |
| − |
| |
| − | This page describes the development process for Capella. In particular, it describes the methodology to be followed to contribute to Capella and the tooling provided to achieve this goal.
| |
| | | | |
| | A good starting point for reading is PolarSys [[The_Forge]] that gives an overview of the process in terms of tooling. | | A good starting point for reading is PolarSys [[The_Forge]] that gives an overview of the process in terms of tooling. |
| Line 8: |
Line 5: |
| | The instructions in this page follow the rules defined in the [https://polarsys.org/wiki/PolarSys_Software_Development_Plan_For_Capella_And_Kitalpha ''PolarSys Software Development Process for Capella and Kitalpha''] document. | | The instructions in this page follow the rules defined in the [https://polarsys.org/wiki/PolarSys_Software_Development_Plan_For_Capella_And_Kitalpha ''PolarSys Software Development Process for Capella and Kitalpha''] document. |
| | Please refer to this document for additional information. | | Please refer to this document for additional information. |
| − |
| |
| − | = Requirements =
| |
| − |
| |
| − | Any change, whether as bug correction or evolution made to Capella, requires the '''creation''' and '''acceptance''' of a bug in Bugzilla. <br />
| |
| − | Requirements, in case of an evolution, are to be proposed in the description of the bug in Bugzilla. Evolutions are also open to debate in the '''forum''' for instance. They also will be discussed in roadmap meetings but any proposal is welcome. <br />
| |
| − | Current functionalities are described in the documentation. <br />
| |
| − |
| |
| − | = Change Management =
| |
| − |
| |
| − | Bugzilla is the general-purpose bug tracker used for Capella.
| |
| − | It can be accessed using http://polarsys.org/bugs/describecomponents.cgi?product=Capella
| |
| | | | |
| | = Development Environment = | | = Development Environment = |
| − | | + | https://github.com/eclipse/capella/wiki/Development-Environment |
| − | == In a standard Eclipse Plugin Development platform ==
| + | |
| − | | + | |
| − | - If you intend to contribute to Capella core code (for addons developements, you shall use a Capella Studio), one way is to use an standard Eclipse and run Capella as a Target Platform.
| + | |
| − | | + | |
| − | ''Windows'' > ''Preferences'' > ''Plugin Development'' > ''Target Platform'' and set the eclipse folder of a Capella installation.
| + | |
| − | | + | |
| − | When running as Normal/Debug, you just have to choose "org.polarsys.capella.rcp.product" as "Product to Run"
| + | |
| − | | + | |
| − | ''Run'' > ''Run Configurations'' > Double Click on ''Eclipse Application'' to create a new Running Platform > ''Program to Run'' > "org.polarsys.capella.rcp.product"
| + | |
| − | | + | |
| − | == Capella Studio ==
| + | |
| − | | + | |
| − | A development environment can also be configured manually by Installing a Capella Studio and install GIT adapter in it.
| + | |
| − |
| + | |
| − | * First, [http://polarsys.org/capella/download.html download] and run '''Capella Studio''' ;
| + | |
| − | | + | |
| − | * After launch, open ''Help'' then ''Install new software...'' wizard ;
| + | |
| − | | + | |
| − | * Type in [http://www.eclipse.org/egit/download/ EGit update site URL] in ''Work with'' field and press ENTER ;
| + | |
| − | | + | |
| − | * Tick ''Eclipse Git Team Provider'' then ''Next'' twice and ''Finish''.
| + | |
| − | | + | |
| − | * Open ''Windows'' then ''Open Perspective'' and select ''Other.. Git'' ;
| + | |
| − | | + | |
| − | == Automated Setup ==
| + | |
| − | | + | |
| − | - Another way to setup a capella development environment is by using the eclipse installer. See the [[Capella/Oomph_Setup|Oomph Setup]] page for more info. | + | |
| − | * Wait and Accept when asked for restart ;
| + | |
| | | | |
| | = Contribute to GIT code= | | = Contribute to GIT code= |
| − | | + | https://github.com/eclipse/capella/wiki/Contributing |
| − | Contributions are welcome, please read above for contribution process.
| + | |
| − | | + | |
| − | == URIs for Capella repositories ==
| + | |
| − | | + | |
| − | === Capella Git ===
| + | |
| − | | + | |
| − | <pre>https://git.polarsys.org/r/capella/capella</pre>
| + | |
| − | | + | |
| − | <pre>https://git.polarsys.org/gitroot/capella/capella.git (readonly)</pre>
| + | |
| − | | + | |
| − | === Capella Addons ===
| + | |
| − | | + | |
| − | <pre>https://git.polarsys.org/r/capella/capella-addons</pre>
| + | |
| − | | + | |
| − | <pre>https://git.polarsys.org/gitroot/capella/capella-addons.git (readonly)</pre>
| + | |
| − | | + | |
| − | === Capella Studio ===
| + | |
| − | | + | |
| − | <pre>https://git.polarsys.org/r/capella/capella-studio</pre>
| + | |
| − | | + | |
| − | <pre>https://git.polarsys.org/gitroot/capella/capella-studio.git (readonly)</pre>
| + | |
| − | | + | |
| − | == Workflow for contributions ==
| + | |
| − | | + | |
| − | It follow standard development contributions.
| + | |
| − | * Clone Git Repository
| + | |
| − | * Create a bugzilla ticket
| + | |
| − | * Create a local branch and do changes: code, but also updating documentation and add/update automated tests
| + | |
| − | * Push to Gerrit the changes to start review process
| + | |
| − | * Wait for the merge
| + | |
| − | | + | |
| − | === Clone repository from Gerrit ===
| + | |
| − | | + | |
| − | [https://wiki.eclipse.org/EGit/User_Guide/Remote#Cloning_remote_Repositories EGit Cloning remote Repositories]
| + | |
| − | | + | |
| − | * Select ''Clone a Git repository'' for cloning one of Capella '''Gerrit''' repository above (Capella, Capella-addons, Capella-studio).
| + | |
| − | | + | |
| − | * Type in the wizard field URI the selected repository URI of interest ; All other fields are filled ; and Press ''Next''. Choose a local Directory to save the repository and press ''Finish''
| + | |
| − | | + | |
| − | * The repository is now displayed in the ''Git Repositories'' view.
| + | |
| − | | + | |
| − | | + | |
| − | === Gerrit configuration for the Git repository ===
| + | |
| − | | + | |
| − | * Expand the repository, and open the contextual menu on ''Remotes'' > ''origin'' > ''Gerrit Configuration''. A wizard is displayed ;
| + | |
| − | | + | |
| − | * ''Push URI'' shall be filled ; Otherwise, use the same as previously entered ; Press '''OK'''
| + | |
| − | | + | |
| − | * A greeen decorator is added to the repository in ''Git Repositories'' view showing Gerrit configuration succeeded ;
| + | |
| − | | + | |
| − | | + | |
| − | === Create a Local Branch and import projects ===
| + | |
| − | | + | |
| − | * Expand the repository in ''Git Repositories'' view ; Expand ''Branches'' then ''Remote Tracking'' folder ;
| + | |
| − | | + | |
| − | * Double-click on ''origin/master'' branch in order to create a local working branch ; (master is the latest one)
| + | |
| − | | + | |
| − | * Select ''Checkout as New Local Branch'' when prompted ;
| + | |
| − | | + | |
| − | * The branch is displayed in ''Branches'' / ''Local'' folder ;
| + | |
| − | | + | |
| − | * Now right-click on ''Working Directory'' folder and select ''Import Projects...'' ;
| + | |
| − | | + | |
| − | * Projects are imported into the workspace ;
| + | |
| − | | + | |
| − | | + | |
| − | === Contribute code : Commit and Push to Gerrit ===
| + | |
| − | * If you contribute to Capella core, you have to import capella.epf Preferences to use proper text formatting.
| + | |
| − | (''File'' > ''Import'' > ''General'' > ''Preferences'' and choose the ''capella.epf'' at the root of Capella Git repository with all options checked)
| + | |
| − | | + | |
| − | * Make sure you created a [https://polarsys.org/bugs Bugzilla] ticket before starting work.
| + | |
| − | | + | |
| − | * Perform some changes in the projects ; Open ''Window'' then ''Show View'' and ''Git Staging'' ;
| + | |
| − | | + | |
| − | * Drag-and-drop modified files from the ''Unstaged Changes'' field to the ''Staged Changes'' ;
| + | |
| − | | + | |
| − | * Fill the ''Author'' and ''Committer'' fields as USERNAME <EMAIL> (Its your username and email as defined in your Eclipse account. use [https://dev.eclipse.org/site_login/ this link] to create one))
| + | |
| − | | + | |
| − | * Enter the commit message respecting the chart written for commit message formatting [https://polarsys.org/wiki/PolarSys_Software_Development_Plan_For_Capella_And_Kitalpha#Commit_Messages_Formatting here] ;
| + | |
| − | | + | |
| − | * Click on ''Add Signed-off-by'' button ; Click on ''Commit'' button ;
| + | |
| − | | + | |
| − | * Go back to ''Git'' perspective ;
| + | |
| − | | + | |
| − | * Right-click on the repository and select ''Push to Gerrit'' option ; (Push to Gerrit, not Push as direct Push are not allowed). On push, you will be asked for credentials which are your username and http password defined [https://git.polarsys.org/r/#/settings/http-password here]. (you can connect to this site using your Eclipse account)
| + | |
| − | | + | |
| − | * Verify the Gerrit branch is the same as the one on which you had created a local branch;
| + | |
| − | | + | |
| − | * The Eclipse Git tooling shows a dialog after its push, which contains, if the push was successful a URL to the Gerrit review. Is also contains error messages in case the push was not successful ;
| + | |
| − | | + | |
| − | * Wait for the review!
| + | |
| − | | + | |
| − | | + | |
| − | === Improve a change based on review feedback ===
| + | |
| − | | + | |
| − | If the review process has resulted review comments explaining how to improve the proposed patch, you will have to adjust the patch. To do so, you amend the commit in your local repository and push the improved commit to Gerrit.
| + | |
| − | | + | |
| − | As you amend the commit, the same Change-Id is used and the Gerrit review system identifies the change as update of the existing change. The Git Staging view allows amending the last commit by clicking the amend button.
| + | |
| − | | + | |
| − | Further details at [https://polarsys.org/wiki/PolarSys_Software_Development_Plan_For_Capella_And_Kitalpha#Gerrit_Review this address].
| + | |
| − | | + | |
| − | = Capella code requirements =
| + | |
| − | | + | |
| − | == Code Formatting ==
| + | |
| − | If you contribute to Capella core, you have to import capella.epf Preferences to use proper text formatting.
| + | |
| − | (''File'' > ''Import'' > ''General'' > ''Preferences'' and choose the ''capella.epf'' at the root of Capella Git repository with all options checked)
| + | |
| − | | + | |
| − | == License headers for new source files ==
| + | |
| − | | + | |
| − | Before submitting a patch, make sure that newly added source files have a proper license header. The license header must be applied to .java, .xml, .properties files.
| + | |
| − | You can refer to an existing file to see Copyright header format.
| + | |
| − | | + | |
| − | == Update documentation ==
| + | |
| − | | + | |
| − | Before submitting a patch, make sure that documentation is updated accordingly to new added features and changed interfaces.
| + | |
| − | Please refer to section Documentation to see how to update documentation.
| + | |
| − | | + | |
| − | == Add/Update Automated tests ==
| + | |
| − | | + | |
| − | Before submitting a patch, make sure that new added features and fixed issues are covered by automated tests.
| + | |
| − | Tests are defined in tests/ git repository.
| + | |
| | | | |
| | = Capella components = | | = Capella components = |
| − | | + | https://github.com/eclipse/capella/wiki/Development-How-To |
| − | == Capella Source Breakdown ==
| + | |
| − | | + | |
| − | Each directory is composed by two sub-directories, features and plugins.
| + | |
| − | <br />
| + | |
| − | Capella source code is organized as follow:
| + | |
| − | * '''Common''': Generic plugins, independent from Capella metamodel. Used by various plugins ;
| + | |
| − | * '''Core''': Plugins dependent from Capella metamodel (Regarding charts, transitions, model validation, queries on semantic browser, property views, etc.) ;
| + | |
| − | * '''Legacy''' : Obsolete dependencies ;
| + | |
| − | * '''Doc''': Capella documentation plugins - documentation as Eclipse documentation (e.g. Eclipse help menu) ;
| + | |
| − | * '''M2''': Capella metamodel (ecore files) ;
| + | |
| − | * '''Releng''' : Code generation plugins (Generate Capella EMF code from ecore metamodels) and generation of builds and continuous integration jobs (Maven/Tycho).
| + | |
| | | | |
| | == Capella Metamodel == | | == Capella Metamodel == |
| − | | + | https://github.com/eclipse/capella/wiki/Metamodel |
| − | === Getting the Metamodel ===
| + | |
| − | | + | |
| − | There are two ways to retrieve Capella Metamodel ecore files :
| + | |
| − | * From the available builds, open the plugins (with winzip, 7zip, ...) then extract the ecore files from the sub-directories '''model''':
| + | |
| − | ** ''org.polarsys.capella.common.data.core.gen''
| + | |
| − | ** ''org.polarsys.capella.common.data.behavior.gen''
| + | |
| − | ** ''org.polarsys.capella.common.data.activity.gen''
| + | |
| − | ** ''org.polarsys.capella.core.data.gen''
| + | |
| − | * From Capella git repository in the directories:
| + | |
| − | ** ''GITROOT/org.polarsys.capella/m2/plugins/org.polarsys.capella.common.data.def/model''
| + | |
| − | ** ''GITROOT/org.polarsys.capella/m2/plugins/org.polarsys.capella.core.data.def/model''
| + | |
| | | | |
| | === Generating the Metamodel === | | === Generating the Metamodel === |
| − | This step can only be done in a Capella Studio environment
| + | https://github.com/eclipse/capella/wiki/Development-How-To |
| − | | + | |
| − | * Import all releng project, ''*gen'', ''*.gen.edit'' from '''core''' and '''common''' plugins, and '''m2''' folder ;
| + | |
| − | * Import in your workspace *emde.model and *emde plugins from Capella Studio.
| + | |
| − | * Do your modifications into m2 folder ecore (data.def) ;
| + | |
| − | * Run EGF Activity ''org.polarsys.capella.common.extension.migration.egf'' / G3&G4, this will copy data.def M2 into data.gen ;
| + | |
| − | * Run ''org.polarsys.capella.core.egf'' root EGF Activity to generate EMF code.
| + | |
| | | | |
| | == Release Engineering == | | == Release Engineering == |
| − |
| |
| − | === Continuous Integration System ===
| |
| − |
| |
| − | Capella HIPP ([http://hudson-ci.org/ Hudson] instance) is available at:
| |
| − |
| |
| − | <pre>
| |
| − | https://ci.polarsys.org/capella/
| |
| − | </pre>
| |
| − |
| |
| − | === Download Space / Storage ===
| |
| − |
| |
| − | The storage place for Capella milestones, snapshots and documentation is available at:
| |
| − |
| |
| − | <pre>
| |
| − | http://download.polarsys.org/capella/
| |
| − | </pre>
| |
| − |
| |
| − | === Third-party Dependencies ===
| |
| − |
| |
| − | Capella add-ons depend on Capella plugins in order to be built.
| |
| − |
| |
| − | Capella solution depends on:
| |
| − | * QueryLegacy
| |
| − | * Eclipse Orbit
| |
| − | * EMF Diff/Merge
| |
| − | * Patterns
| |
| − | * Sirius
| |
| − | * Kitalpha
| |
| − | * Eclipse plugins
| |
| − |
| |
| − | These dependencies are resolved during the build, the path to their update site is provided in the build model.
| |
| − |
| |
| − | Please continue to the next section.
| |
| | | | |
| | === Jobs Configuration === | | === Jobs Configuration === |
| − | | + | https://github.com/eclipse/capella/wiki/Development-How-To |
| − | Jobs are separated between Capella solution and its add-ons but the underlying building process is the same.
| + | |
| − | | + | |
| − | In the source code, identify the releng plugin:
| + | |
| − | * ''org.polarsys.capella.core.releng'' for Capella
| + | |
| − | * ''org.polarsys.capella-addons.releng'' for add-ons;
| + | |
| − | | + | |
| − | They are based on Maven Tycho.
| + | |
| | | | |
| | = Documentation = | | = Documentation = |
| − | | + | https://github.com/eclipse/capella/wiki/Development-How-To |
| − | == Capella ==
| + | |
| − | | + | |
| − | Documentation is embedded into the workbench or online through [http://help.polarsys.org/help/index.jsp help.polarsys.org]
| + | |
| − | It is available through ''Help'' menu and ''Capella guide''
| + | |
| − | | + | |
| − | Capella documentation is stored in Capella Git repository '''git.polarsys.org/c/capella/capella.git/tree/doc/plugins'''.
| + | |
| − | | + | |
| − | To create/update documentation, [https://eclipse.org/mylyn/downloads/ Mylyn/Wikitext] must be installed in you IDE.
| + | |
| − | | + | |
| − | Some characteristics of a documentation plugin for Capella:
| + | |
| − | | + | |
| − | * Contribute to the extension point ''org.eclipse.help.toc'' ;
| + | |
| − | * Is written using [https://www.mediawiki.org/wiki/Help:Formatting MediaWiki] syntax ;
| + | |
| − | * Has only '''one''' table of contents ; that lists all chapters of this documentation ;
| + | |
| − | * Has the ant script that is necessary to produce HTML documentation from *.mediawiki source files ;
| + | |
| − | * Is structured as follow:
| + | |
| − | <pre>
| + | |
| − | <plugin_name>
| + | |
| − | /html
| + | |
| − | /<functionality>
| + | |
| − | // Mediawiki and HTML source files
| + | |
| − | /Images
| + | |
| − | // Place all images in this directory
| + | |
| − | build.xml
| + | |
| − | plugin.xml
| + | |
| − | about.html
| + | |
| − | toc.xml
| + | |
| − | build.properties
| + | |
| − |
| + | |
| − | with <plugin_name> = org.polarsys.capella.<functionality>.doc
| + | |
| − | </pre>
| + | |
| − | | + | |
| − | Ensure that:
| + | |
| − | * ''plugin.xml'' contains the contribution to the ''org.eclipse.help.toc'' extension point
| + | |
| − | ** The contents of the contribution shall include the table of contents of the plugin, i.e. ''toc.xml''
| + | |
| − | * The root tag of ''toc.xml'' links to the anchor of the main table of contents ''PLUGINS_ROOT/org.polarsys.capella.doc/toc.xml#<anchor>''
| + | |
| − | | + | |
| − | Contribute to the documentation modifying a Mediawiki file in the ''<html>/<functionnality>'' directory or create a new Mediawiki file in case you would like to add a new chapter. In case of a '''creation''' of a new Mediawiki file, do not forget to update the ''toc.xml'' in order to create a new '''Topic''' accordingly.
| + | |
| − | | + | |
| − | Before testing the contribution, the documentation first needs to be transformed into HTML.
| + | |
| − | | + | |
| − | To do so, right-click on the ''build.xml'' file and select ''Run as'' > ''External Tools Configuration...''. Ensure that in ''JRE'' tab, the option ''Run in the same JRE as the workspace'' is selected otherwise tick it. Then press ''Run'' button. The generation starts and in logged in the console window.
| + | |
| − | | + | |
| − | When the generation ends with success, you can test it by launching Capella target platform then launching the Help menu.
| + | |
| − | | + | |
| − | = Communication =
| + | |
| − | | + | |
| − | * You can subscribe to the [http://polarsys.org/mailman/listinfo/capella-dev capella-dev@polarsys.org] developers mailing list to be warned by Email about technical announcements.
| + | |
| − | * In the [http://polarsys.org/forums/index.php/f/10/ forum], you can submit ideas, share knowledge with users and developers and ask questions about Capella.
| + | |
| − | * The [http://polarsys.org/capella/community.html community] page of Capella website also provides e-mail contact and support from Arcadia and Capella experts.
| + | |
| − | ** In this page you will also find links to '''LinkedIn''' and '''Twitter''' pages of Capella. Stay tuned!
| + | |
| − | * Wikipedia now references [https://en.wikipedia.org/wiki/Capella_(engineering) Capella] and [https://en.wikipedia.org/wiki/Arcadia_(engineering) Arcadia]
| + | |
| − | | + | |
| − | = Quality Assessment =
| + | |
| − | | + | |
| − | Capella continuous integration system has been enriched with [http://www.sonarqube.org/ SonarQube] for managing code quality.
| + | |
| − | | + | |
| − | Moreover, PolarSys Maturity Assessment tool assesses quality in a larger way using quality model and metrics.
| + | |
| − | | + | |
| − | Access to Capella SonarQube results [https://dev.eclipse.org/sonar/dashboard/index/61660 here].
| + | |
| − | | + | |
| − | Access to Capella Maturity Assessment results [http://dashboard.polarsys.org/projects/polarsys.capella.html here].
| + | |
| − | | + | |
| − | | + | |
| − | | + | |
| | | | |
| | [[Category:Capella]][[Category:Kitalpha]] | | [[Category:Capella]][[Category:Kitalpha]] |
