Project

General

Profile

Adding a new plugin to the AutoFOCUS3 build

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: 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 redmine (this page) 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 same file, add the plugin to list of plugins (keep lexicographic order!)
  5. 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"
  6. likewise, set plugin name and vendor in plugin.properties
  7. 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

Adding an repository containing "unoffical" plugins to the AF3 repository.

This part of the documentation has not been tested yet. Please consult Alexander Diewald (see users) first, before performing the following steps. The following steps are instructions that are untested and "should work".

  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 followin 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. Start eclipse.
  2. Create a new branch for developer product definition by right-clicking org.fortiss.af3.phoenix.product.feature and following the typical "switch to" procedure. (see Development Workflow)
  3. Add the plugin to org.fortiss.af3.phoenix.product.feature/feature.xml to the "require" section (keep lexicographic order!)
  4. Upload the result and create a MR in the af3_dev_product repository (https://git.fortiss.org/af3/af3_dev_product)

Update Oomph installation script

  1. Import the plugin fortiss-std-dev into your local workspace: File > Import > Git > Local repository > Select the git folder of your eclipse installation (see above) > Select "fortiss-std-env" and finish the import.
  2. Create a branch for this plugin nambed 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

Update the jenkins compilation recipes

Note: in case you are adding a plugin to the kernel, please substitute "af3" by "kernel"

  1. Import the git repository from https://git.fortiss.org/af3/jenkins-af3
  2. Create a branch with the issue number from above.
  3. Add your plugin to 01_compile/pom.xml (keep lexicographic order!).
  4. Add your plugin to 02_compile/pom-continuous.xml (keep lexicographic order!).
  5. Add your plugin to 02_compile/pom-nightly.xml (keep lexicographic order!).
  6. Add your plugin to 02_compile/pom-release.xml (keep lexicographic order!).
  7. Add your plugin to 02_compile/org.fortiss.af3.phoenix.latest.feature/feature.xml (keep lexicographic order!).
  8. Add your plugin to 02_compile/org.fortiss.af3.phoenix.nightly.feature/feature.xml (keep lexicographic order!).
  9. Add your plugin to 02_compile/org.fortiss.af3.phoenix.release.feature/feature.xml (keep lexicographic order!).
  10. Add your plugin to 02_test/pom.xml (keep lexicographic order!).
  11. Add your plugin to 03_rawproduct/org.fortiss.af3.phoenix.latest.feature/feature.xml (keep lexicographic order!).
  12. Add your plugin to 03_rawproduct/org.fortiss.af3.phoenix.nightly.feature/feature.xml (keep lexicographic order!).
  13. Add your plugin to 03_rawproduct/org.fortiss.af3.phoenix.release.feature/feature.xml (keep lexicographic order!).
  14. Commit & Push the results.
  15. Create a MR to master at https://git.fortiss.org/af3/jenkins-af3

Notify other developers

  1. Write a mail to the developer mailing list that contains the following information:
    1. Update your local af3 repository (git pull)
    2. Import the new plugins using File > Import > Git > Local repository > Select the git folder of your eclipse installation (see above) > ADD THE PLUGIN LIST HERE.
  2. Maybe also notify the others via the AF3 mattermos channel.

Removing a plugin

To remove a plugin, perform the following steps
  1. Verify that your developer does not contain any references
    (by deleting it from your workspace - org.fortiss.af3.phoenix.product.feature/feature.xml)
  2. Verify that the plugin's documentation has been removed
  3. Remove the plugin from the af3 repository locally.
    1. Create an issue.
    2. Create a new branch for your local af3 repo.
    3. Remove the corresponding entries in the .gitmodules file at the root of your af3 repo (see "Adding an repository containing "unoffical" plugins to the AF3 repository")
    4. Commit & push the result.
    5. Create a MR.
  4. Remove the plugins from the jenkins setup by applying the steps in ("Update the jenkins compilation recipes"): Substitute "Add" by "Remove".
  5. If applicable, remove the plugin regex from the oomph file (see above). Ensure that no other plugins are affected by this.
  6. send an email to everybody informing that they should update their workspace, i.e. delete the plugins from the workspace (typically also from disk)

ATTIC (svn instructions)

Adding a new plugin to the AutoFOCUS3 nightly build

  1. if not present already, add a pom.xml in your plugin
  2. check that all resources that are required by your plugin are included in the Binary Build in build.properties (e.g., icons)
  3. add the plugin to org.fortiss.af3.phoenix.product.feature/feature.xml to the "require" section (keep lexicographic order!)
  4. in the same file, add the plugin to list of plugins (keep lexicographic order!)
  5. 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"
  6. likewise, set plugin name and vendor in plugin.properties
  7. give Jenkins the right to access your plugin(s) (respectively ask someone who has the right to do it) -- in most cases there is actually nothing to do
  8. 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

Continuous build

  1. if not already present in your workspace, checkout the "jenkins" folder of the SVN repository; check the "ignore externals" option! otherwise another (useless) copy of all plugins will be checked out
  2. add the plugin to /jenkins/af3/phoenix/continous/00_source/svn.externals, to the list of plugins at the end of the file (keep lexicographic order!)
    if the plugin is a *.ui plugin, add it to list of other *.ui plugins (keep lexicographic order!)
  3. set the svn:externals property of the /jenkins/af3/phoenix/continous/00_source/ folder to the contents
    of the complete text of /jenkins/af3/phoenix/continous/00_source/svn.externals (which you just modified):
    1. copy the content of svn.externals
    2. rightclick on the folder and select Team -> Show properties
    3. in the view which just opened, double-click on the svn:external property
    4. Replace the complete text with the content of svn.externals
    5. CAVEAT: On Windows, you might have to temporarily convert the line breaks of the contents of the svn.externals before pasting it (especially, if using the TortioseSVN client)
  4. add your plugin(s) to the following files, keeping the lexicographic order
    1. /jenkins/af3/phoenix/continous/01_compile/pom.xml
    2. /jenkins/af3/phoenix/continous/02_p2site/org.fortiss.af3.phoenix.latest.feature/feature.xml
    3. /jenkins/af3/phoenix/continous/02_p2site/pom.xml
    4. /jenkins/af3/phoenix/continous/02_test/pom.xml
    5. /jenkins-af3/af3/phoenix/continuous/03_rawrelease/org.fortiss.af3.phoenix.product.release.feature/feature.xml

See attached file af3-product-add-plugins.patch for blueprint of required changes.

Nightly build

  1. add the plugin to /jenkins/af3/phoenix/nightly/00_source/svn.externals, to the list of plugins at the end of the file (keep lexicographic order!)
    if the plugin is a *.ui plugin, add it to list of other *.ui plugins (keep lexicographic order!)
  2. set the svn:externals property of /jenkins/af3/phoenix/nightly/00_source/ to the contents
    of the complete text of /jenkins/af3/phoenix/nightly/00_source/svn.externals (which you just modified):
    1. copy the content of svn.externals
    2. rightclick on the folder and select Team -> Show properties
    3. in the view which just opened, double-click on the svn:external property
    4. Replace the complete text with the content of svn.externals
    5. CAVEAT: On Windows, you might have to temporarily convert the line breaks of the contents of the svn.externals before pasting it (especially, if using the TortioseSVN client)
  3. add your plugin(s) to the following files, keeping the lexicographic order
    1. /jenkins/af3/phoenix/nightly/01_compile/pom.xml
    2. /jenkins/af3/phoenix/nightly/02_p2site/org.fortiss.af3.phoenix.nightly.feature/feature.xml
    3. /jenkins/af3/phoenix/nightly/02_p2site/pom.xml
    4. /jenkins-af3/af3/phoenix/nightly/03_rawproduct/org.fortiss.af3.phoenix.product.nightly.feature/feature.xml

See attached file af3-product-add-plugins.patch for blueprint of required changes.