AF3 Plugins Conventions
=======================

Naming conventions
------------------

We distinguish consistently between plugins concerning the AF3 modeling
language and its user interface implementation.  
The naming convention is

    org.fortiss.af3.the_plugin

  
for the language (meta-model, semantic functionality), and

    org.fortiss.af3.the_plugin.ui

  
for the presentation and user interaction implementation.

Top-level Packages
------------------

The modeling language plugins will adhere to the following list of
top-level packages.

**model**: The EMF meta-model classes. This package is usually found in
*generated-src* folder.  
**annotations**: Implementation related to the annotation framework.  
**compose**: Implementations of compositors.  
**constraint**: Implementations of constraints.  
**generator**: Implementations of generators (if the language supports
that). Target language identifier is usually the next level of package
names, e.g. **generator.java**.  
**prototypes**: Implementation of prototypes.  
**simulator**: Implementations of a simulator backend (if the language
supports that).  
**utils**: Utility classes and methods. Classes in this package only
contain static implementations.

The user interface plugins will adhere to the following list of
top-level elements.

**editor**: Implementations of editors.  
**editpart**: Implementations of graphical editors’ parts.  
**handler**: Implementations of model element handlers.  
**properties**: Implementations of property sections.  
**simulator**: Implementations of a simulator front-end (if the language
supports that).  
**utils**: Utility classes and methods. Classes in this package only
contain static implementations.

Adding a new plugin
===================

The addition of a plugin to AF3 mainly consists of adding the plugin to
the AF3 repository, adjusting the developer product files and installer,
and registering it at the maven/jenkins config files. The following
section explain these steps in detail.



Preparational steps & checks
----------------------------

1.  Ensure that your plugin is entirely [code-reviewed](Check-list_for_Code
____Reviews): The plugin must be marked “green” in the
    eclipse package explorer. If not, ask a colleague (or several) to do
    a review of your plugin. The plugin(s) will only be added if they
    are “green”.
2.  Create a ticket in GitLab about the integration of your
    plugin.
3.  Check that all resources that are required by your plugin are
    included in the *Binary Build* in `build.properties` (e.g., `icons`)
4.  In the `META-INF` of your plugin, set the version to 2.x.0.qualifier
    (x to be replaced to match the current version of AF3), the name of
    the plugin to your plugin name, and the name of the vendor to
    “fortiss GmbH”
5.  likewise, set plugin name and vendor in `plugin.properties`
6.  Especially for plugins that have been under development for a longer
    time, verify that the plugin is compliant with the plugin templates
    (e.g., builder configuration, scripts, directory layout, …)  
    - `fortiss-std-env/base-project/org.fortiss.af3.base.project.ui`
    for model / functionality plugins  
    -
    `fortiss-std-env/base-project/org.fortiss.af3.base.project.ui.zip`
    for UI plugins

If needed: Adding a repository containing “unofficial” plugins to the AF3 repository (and it should remain “unofficial”)
--------------------------------------------------------------------------

1.  Close eclipse
2.  Ensure that the command line version of git is installed on your system (“git” on Linux/MacOSX, “MsysGit” recommended for windows).
3.  Create a new branch in the your local AF3 repository that matches the number of the issue you created before:      

        git checkout -b <issuenum> # replace <issuenum>
       
4.  open a shell and go to the af3 repository of your eclipse installation (typically <eclipse-root>/autofocus3-master/git/af3).
5.  execute the following sequence of commands, where “project-a” are the plugins to be integrated into “project-b”

        git remote add project-a https://git.fortiss.org/af3/project-a
        git fetch project-a
        git merge --allow-unrelated-histories project-a/master # or whichever branch you want to merge
        git remote remove project-a
        

6.  afterwards, add the .settings submodule entry in the “.gitmodules” file located at the root of the af3 repo. this might have already be done during the merge. see the other entries about the formatting.
7.  upload the result to the server by issuing
        
        git push origin <issueNum>:<issueNum> # Replace <issueNum>
        
8.  Go to https://git.fortiss.org/af3 and log in. Create a merge request (MR) from your just uploaded branch to master.

Register the plugin with the developer product definitions
----------------------------------------------------------

1. Create a new branch for developer product definition by right-clicking `org.fortiss.af3.phoenix.feature` and following the typical “switch to” procedure. (see [Development Workflow](Development_Workflow))
2.  Add the plugin to the list of plugins in `org.fortiss.af3.phoenix.feature/feature.xml` (keep lexicographic order!)
3.  Upload the result and create a MR at [https://git.fortiss.org/af3/af3-features](https://git.fortiss.org/af3/af3-features) (the merge should not be executed until the actual plugin is merged in the af3 and/or kernel repos!)

Update Oomph installation script
--------------------------------

1.  Import the plugin `fortiss-std-dev` into your local workspace: File > Import > General > Existing Projects into Workspace > Select the git folder of your eclipse installation > Select “fortiss-std-env” and finish the import.
2.  Create a branch for this plugin named by the issue number from the above steps.
3.  Open the Oomph setup file (oomph/af3.setup) in eclipse and go to “Working sets”.
4.  Add the plugin to the corresponding plugin set, e.g., “Behaviour”, if it is not yet captured by any of the existing regular
    expressions.
5.  Commit & push the result.
6.  Create a MR to master at [https://git.fortiss.org/af3/fortiss-std-env](https://git.fortiss.org/af3/fortiss-std-env) (the merge should not be executed until the actual plugin is merged in the af3 and/or kernel repos!)

Adjust the Run Configurations to consider the added plugins
------------------------------------------------------------
1. Create a new branch for https://git.fortiss.org/af3/af3-products (according to your issue number).
2. Add there in all three config files (win64.launch, linux64.launch, mac64.launch) your new plugins after the "selected_workspace_bundles" key similar to the already existing plugins (like `<setEntry value="org.fortiss.XXX.XXX@default:default"/>`).
3. Commit & push the result.
4. Create a MR to master at [https://git.fortiss.org/af3/af3-products](https://git.fortiss.org/af3/af3-products) (the merge should not be executed until the actual plugin is merged in the af3 and/or kernel repos!)

Adjust the Maven build process to consider the added plugins
------------------------------------------------------------

1.  Install an AF3 developer installation for local building as described in the [local build documentation](https://git.fortiss.org/af3/af3/-/wikis/Setting_up_a_local_build#local-build). This will enable you to perform a Maven Build to get in the end a local AF3 build. However, do not execute yet the Maven Build (skip the third step ["triggering a maven build"](https://git.fortiss.org/af3/af3/-/wikis/Setting_up_a_local_build#triggering-a-maven-build)), because you need to adjust some parts of the Maven Build for your new plugin(s): see next step.
2.  Follow the steps described in ['Adjust your build'](https://git.fortiss.org/af3/af3/-/wikis/Setting_up_a_local_build#adjust-your-build) (not everything there might be needed, but the adjustment of the POM file is definitely something that needs to be done).
3. You should now check if you could build with all your changes/adjustments a local AF3 build. For that go back to the [local build documentation](https://git.fortiss.org/af3/af3/-/wikis/Setting_up_a_local_build#local-build) and execute the previously skipped third step of ["triggering a maven build"](https://git.fortiss.org/af3/af3/-/wikis/Setting_up_a_local_build#triggering-a-maven-build). If it can be build successfully, you should be ready to merge all your changes.
4. Merge your branches for the adjusted build to master. Hereby, it is important to start with the MR for maven-releng to make the pipelines of all other MRs succeed. A reasonable order for merging is for example: `maven-releng -> af3-rcp -> tooling-features -> kernel -> af3-features -> af3 -> af3-tests` (Note, that usually not all of these repositories need to be adjusted for adding a new plugin!)