AF3-Eclipse Platform
====================

Typically, we update the base eclipse platform after each AF3 release to
the most recent Eclipse version. By that we have enough time to discover
regressions or other bugs that impact our work. If there are major
issues, the update is held back until those are resolved.

Updating the eclipse platform
-----------------------------

### Preparation

As a developer that intends to update the AF3 platform, please perform
the following steps to make your local installations aware of the test
updates and to ease editing the af3 setup file.

1.  Clone the repository
    `https://git.fortiss.org/af3/fortiss-std-env.git` to your computer
    and remember the path to it. Switch to a working branch.
2.  Open the file
    q<HOME>/.eclipse/org.eclipse.oomph.setup/setups/org.eclipse.projects.setup@
    in a text editor of your choice. In Windows, substitute `<HOME>`
    with `C:\Users\<Username>`; In Linux/MacOS with the home folder
    `/home/<Username>`.
3.  Search for the line mentioning `af3.setup` and replace the line with
    (NOTE: No Copy/Paste!):
    "file:/<PATH-TO-FORTISS-STD-ENV>/oomph/af3.setup#/"
4.  Start (or restart) an AutoFOCUS 3 developer installation and check
    that the corresponding Oomph file points to the update location:
    Open “Window/Edit >Preferences >Oomph >Setup Tasks” and
    check the window title.
5.  Ensure that the option “Skip automatic task execution at startup
    time” is UNCHECKED to receive updates.
6.  Restart eclipse.
7.  By opening “Window/Edit >Preferences >Oomph >Setup
    Tasks”, you can edit the setup file. Alternatively, you can also
    import the previously cloned repo in your eclipse installation to
    ease the git interaction.

### What to update?

**Oomph File:**

1.  Update the version identifier to the recent release.
2.  P2 Eclipse update site
   1.  Update URLs to the recent release.
   2.  Update version numbers: See [Eclipse 2019-09](https://download.eclipse.org/oomph/archive/reports/download.eclipse.org/releases/2019-09/index.html)
        and [EPP packages 2019-09](https://download.eclipse.org/technology/epp/packages/2019-09/) for the EPP packages.
3.  P2 eGit / jGit update site
   1.  Update URL to the most recent release (see [EGIT FAQ](https://wiki.eclipse.org/EGit/FAQ\#Where\_can\_I\_find\_older\_releases\_of\_EGit.3F)
   2.  Update Version numbers
4.  P2 efxclipse update site
   1.  Update URL to the most recent release (see [e(fx)clipse](https://download.eclipse.org/efxclipse/updates-released/)
   2.  Update version constraints
5.  Update target file reference version.
6.  In the oomph setup file, set the branch of the fortiss-std-env git
    repository to the just created branch.
7.  Commit & Push the result to the remote feature branch.

**Target File:**

1.  Create a branch for the target-definition repo.
2.  Open the target file.
3.  Update the target file version identifier.
4.  Perform the same steps for the P2 Eclipse update site as for the
    oomph file. NOTE: You must specify exact versions here.
5.  Update the URL of the efxeclipse entry to the recent version.
6.  IFF the OpenJFX was updated to a new major version, update its URL.
7.  Update the URL to the Eclipse orbit repository and check for version
    updates. NOTE: Only take the latest R\* version.
8.  Commit & Push the result to the remote feature branch.
9.  In the oomph setup file (fortiss-std-env repo), set the branch of
    the target-file git repository to the just created branch.
10. Commit & Push the result to the remote feature branch.

### Testing & further changes

1.  New Installations: Perform a new installation from the modified
    oomph setup file and fix remaining problems.
2.  Update Installations: When the installation finishes without errors,
    it is about time to restart the eclipse instance in which you edited
    the files above. Then, install updates when prompted.
3.  Use the updated installation (best: more than one person) for a
    couple of days / weeks to discover problems.

### Final step before merging

In the oomph setup file the pointers to the testing branches have to be
reset: Reset all pointers in the git repositories to
`${scope.project.stream.name}`