How to - building a new release
======================

Efficiently upgrading AF3 sources from version a.b.c to d.e.f
-------------------------------------------------------------

Upgrading AF3 (and TK2 version) mainly involves updating the plugin
manifest files, few plugin-specific pom.xml files for maven, and the
product/build configurations.  
This procedure ensures that this can be done manually, but efficiently
by using the Eclipse multi-file search and replace function.

### Preparing the Release Build

1.  Setup a local AF3 maven-releng eclipse according to the instructions 
    found at: [Setting up a local build](Setting_up_a_local_build)
2.  Create a release ticket in the issue tracker, and create a matching
    branch for each submodule.
3.  Check the plugins and remove for redundant dependencies suing re-export.
4.  Select the project `org.fortiss.af3.root` in the Package Explorer
    and execute an Eclipse File Search with the following settings
    (`Ctrl + H`)  
    - Containing text = *a.b.c* (Current version number, e.g.,
    2.14.0)  
    - File name patterns = *\*.product, MANIFEST.MF, category.xml,
    feature.xml, pom.xml, plugin.xml*  
    - Scope = *Selected resource in ’Package Explorer’*  
    - No other search option active.
5.  You may want to inspect the results of this search before launching
    the replace action.
6.  If the changes are fine, right-click in the *Search* view, select
    *Replace all*, and replace the current version string with the
    update one:  
    - Add the new version number into the upcoming dialog and hit
    “OK”  
    - Replace: “a.b.c”  
    - With: “d.e.f”
7.  Use the file search again to find the containing text *a.b* (Current major version number, e.g.,
    2.14). Manually replace the few search results which indeed use the old version number (attention: Not all results will need to be replaced - the search will likely also find false positives!).  
8.  Run a local build by selecting “Run As >Build All” and observe
    if any error occurs.
9.  If the build succeeds, commit the changes. **NOTE:** You must commit
    to multiple repositories. Since these are submodules, you may need
    to specify the remote branch: The issue number from the previously
    created ticket shall be used.
10.  Issue a MR for the plugin `org.fortiss.af3.root` and each of the
    submodules where there has been a version update.
11.  After merging, ensure that the AF3 version is configured correctly. (Check maven releng repository for correct commit messages)

### Update “What’s new” Page

1.  (Manually) filter the previously created “Release Notes” for
    changes, that a user would experience.
2.  In your workspace, open
    org.fortiss.af3.rcapplication/intro/newFeatures.html.
3.  Update version number.
4.  Remove old Entries.
5.  Add entries for the filtered changes in the respective sections.
6.  Commit: It will be automatically added to the MRs imposed earlier.

### Building the release

1.  Ask a master to merge all the MRs created before (Step 8. and 9. of *Preparing the Release Build*). 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-product -> af3-rcp -> tooling-features -> kernel -> af3-features -> af3 -> af3-tests`
2.  Ask a master to trigger the [Build Pipeline](https://git.fortiss.org/af3/maven-releng/-/pipeline_schedules)

### Quality management: Ensure that the final product is behaving correctly

1.  Launch the product. Go to “Help”->“About autoFOCUS3” and check
    that the version number matches the release version
2.  **Verify the test for the binary product listed in
    [AF3 core test cases](Core\_Test\_Cases) are successfully
    completed.**
3.  Especially note that the product must start on all platforms, and
    that the help functionality is working: Ask the platform maintainers
    for assitance.

### Tag the release

1.  Add a tag d.e\[.f\] indicating the current AF3 version to the
    following repositories. Suggested log message:
    `Tag AutoFOCUS3 d.e[.f]`  
    - `af3`  
    - `af3-features`  
    - `af3-products`  
    - `af3-rcp`  
    - `af3-tests`  
    - `kernel`  
    - `maven-releng`  
    - `target-definition`
2.  Push the above repos (including tags)


Help page on the website
------------------------

1.  Empty the smb://fs01/download/public/projects/af3/help directory
    (\\\\FS01\\Download\\public\\projects\\af3\\help)
2.  Copy the contents of the org.fortiss.af3.rcp.help/html directory into
    smb://fs01/download/public/projects/af3/help
3.  Rename `getting_started.html` into `index.html`
4.  Delete all `.ratings` files in this folder and all subfolders (e.g. using the file search)

Update AF3 Website 
------------------

1. Update Downloads folder

   a.  Download the release zips from each of the product jobs.
   
   b.  Change their name, **write the correct version number** (i.e., the new one)
   
   c.  Copy them on downloads.fortiss.org (\\\\FS01\\Download\\public\\projects\\af3\\stable\\phoenix)

2. Update Release Notes:
	
   a.  Display the relevant issues in gitlab (using the various filtering
	    options of gitlab) (all Closed and Resolved issues from Target
	    Version). Include the link into the release notes
   
   b. Create a new html page indicating the major changes of the current release and the link to the detailed list of issues which have been resolved (2.a.)[Release notes](https://www.fortiss.org/veroeffentlichungen/software/autofocus-3/release-notes)

3. Update the webpage by contacting marketing sending the release notes html and the the new link to the current release

Announcements
-------------

Announce the release on:

1.  AF3 main page
2.  Mailing lists af\_user and af\_devel
3.  fortiss main page
4.  Twitter