Breaking changes in Z Open Editor 3.0.0

[phaumer]

Prepare for breaking changes in the next version of Z Open Editor

We previously announced in this thread that there will be a major version update for Z Open Editor in Q4 with breaking changes. So far we only talked about the mandatory switch to Java 11 or newer. In this thread we also want to prepare you for other breaking changes of this release. The lists below shows all the items that we can already talk about based on the current state of development. None of these are 100% guaranteed to make it into the release, but these are most likely to make it into the release. We will make updates to this summary as soon as we know them.

Note, if you do not want to be surprised by an automatic update by VS Code for this release and/or need more time to prepare a migration, then we strongly recommend that you use the VS Code setting extensions.autoUpdate and switch it to false. If you don't want VS Code to even check for updates, you can set the extensions.autoCheckUpdates setting to false. However, this will also prevent updates for other VS Code extensions from being installed.

Features that will be removed/replaced

• Support for Java 8 removed: We will compile all our languages servers with Java 11 for this version of Z Open Editor. You will not be able to run the editor with a Java 8 runtime anymore. You must upgrade to a Java 11 or newer runtime.
• Property groups will not be supported as VS Code settings (zopeneditor.propertygroups) anymore: We are making the full switch to ZAPP files in this release. You need to move all your property groups from your user settings and/or workspace settings to a ZAPP file. Also see the next section for breaking changes for ZAPP property groups. To make the transition easier you could migrate your current user setting to ZAPP files already. At the moment the schema is the same, so you can copy paste these into zapp.json files and adjust them, or use any of the many json-to-yaml converters to convert them to yaml. (I like this extension.)
• User Build workspace setting will not be support as VS Code settings (zopeneditor.userbuild.workspaceSettings) anymore: We are also making here the switch to ZAPP. The exception will be the user build user settings (zopeneditor.userbuild.userSettings). Those will remain.

Breaking feature changes

In addition to moving Property Groups and User Build settings to ZAPP, we are also making schema changes that require updates to existing ZAPP files. All of these changes are driven by enhancements requests by this community, our customers, and our technical representatives that work with customers every day. However, we are in this release not able to address all the enhancements that people proposed and that we want to support. It will be the first increment of changes that require breakages and manual migration on which we can then build for the other updates that we have in mind for future releases that (hopefully) do not require any more manual migration steps.

The following changes require manual updated to your current ZAPP files:

• Renamed properties: We fixed several places in which property names did not follow YAML/JSON naming conventions. The rationale was, "if we are now breaking things with the other changes below, then we might as well fix these now". These need to be simply replaced in your ZAPP files. Note, that the first three properties in the table below are currently not used by Z Open Editor. So if you have used them, then you can also just delete them for now. They are planned to be used in future releases to support multiple ZAPP files and their relationships.

  Old name	New name
  group-id	groupId
  artifact-id	artifactId
  parent-id	parentId
  property-groups	propertyGroups

• Simplified and refactored property groups: Based on suggestions in discussion threads and issues filed in this repository, as well as other feedback from users, we refactored the property groups. The goal was to make writing property groups simpler and avoid redundancies, such as specifying compiler options multiple times. In the new structure you can create one property group per language and provide a list to local or remote locations for it. You can still create several property groups for the same language still, if you want. We also simplified the nesting of the location arrays to less complex by eliminating the special property syslib and instead making it one possible name value. Here is an example for a PL/I property group:

  propertyGroups:
  - name: pl1-includes
      language: pl1
      compilerOptions: not(!)
      libraries:
        - name: syslib
          type: local
          locations:
            - "**/INCLUDES"
            - "TOOLS"
        - name: syslib
          type: mvs
          locations:
            - "IBMUSER.SAMPLE.PLI.PLINC"
            - "IBMUSER.TOOLS.PLI.PLINC"
        - name: MYLIB
          type: mvs
          locations:
            - "IBMUSER.SAMPLE.PLI.INCLLIB"
        - name: MYLIB
          type: local
          locations:
            - "**/INCLUDELIB-MVS"
        - name: MYFILES
          type: local
          locations:
            - "**/INCLUDELIB"

  The libraries array defines the search order for include files. Within each libraries item there can be many locations items that are also searched in the order listed. For the example above, Z Open Editor will first look for regular include files using the entries specified under the name syslib in any local sub-folder that matches the folder name INCLUDES. Second it will search in the one local folder TOOLS that is expected to be at the root of the current VS Code workspace in which the ZAPP file is located. Note, that as in previous releases of Z Open Editor you can use multi-root workspaces with each workspace having its own ZAPP file. The search order will then be determined by the order defined in the .code-workspace file. If Z Open Editor will not find an include file in any of these local folders it will then search in MVS in the data sets listed: IBMUSER.SAMPLE.PLI.PLINC first and IBMUSER.TOOLS.PLI.PLINC second. The same kind of search will be applied to the libraries MYLIB and MYFILES as defined in the example above.

• Required application setting for User Build: In the 2.1.1 and 2.2.0 releases of Z Open Editor we changed the usage of the --application parameter for user build as a quick fix for an issue with multi-root workspaces. The disadvantage of the solution was that programs stored at the top-level folder of a VS Code workspace would be uploaded to the USS workspace without organizing them into an application-specific subfolder. (See 2.1.1 Release notes.) We are planning to address this problem in the next major version of Z Open Editor by introducing a new mandatory setting for DBB ZAPP profiles that defines the application name as required by dbb-zappbuild. Users need to add this setting to their profiles. For example:

  profiles:
    - name: dbb-userbuild
      type: dbb
      settings:
        application: SAM
        command: "$DBB_HOME/bin/groovyz -DBB_PERSONAL_DAEMON"
        buildScriptPath: "${zopeneditor.userbuild.userSettings.dbbWorkspace}/dbb-zappbuild/build.groovy"
        buildScriptArgs:
          - "--userBuild"
          - "--workspace ${zopeneditor.userbuild.userSettings.dbbWorkspace}"
          - "--application ${application}"
          - "--hlq ${zopeneditor.userbuild.userSettings.dbbHlq}"
          - "--outDir ${zopeneditor.userbuild.userSettings.dbbLogDir}"
          - "--dependencyFile ${dependencyFile}"
        additionalDependencies:
          - application-conf

  As you can see in the example, the value of the new application setting can be referenced as a variable ${application} within the profile such as for the Groovy command argument.

[FALLAI-Denis]

Hi @phaumer

I agree that all settings related to source code management must be managed in the zapp.yaml file completely independently of VS Code, in order to be independent of the editor used, (one could imagine using VS Code but also IDz or ZOD to edit source codes), but also to be able to reuse these settings in other contexts, such as for example in our Jenkins pipelines, or IBM DBB (which is not the case at this day).

As such, there is another setting that should migrate from the settings.json file to the zapp.yaml file: zopeneditor.zowe

   "zopeneditor.zowe": {
     "defaultCliProfile": "lpar-zosmf",
     "defaultSshCliProfile": "lpar-ssh",
   }

With the consequence that each user declares the same Zowe CLI profile names, which becomes the case with Zowe CLI V2 if we place the zowe.config.json file in the workspace (Git repository) of VS Code, which we have done, (There is a drawback to this management: the credentials are relative to the location of the zowe.config.json file, therefore managed independently for each workspace / Git repository...).

[phaumer]

Hello @FALLAI-Denis.
Thanks for you feedback to this post and hopefully you recognize some of your requests in these changes. As you mentioned above, we also envision the use of ZAPP independent of Z Open Editor so it can be used by automation or other editors. As some of these will not rely on Zowe profiles to interact with z/OS, but might use other technologies to access resources, we want to separate the Zowe profiles list from ZAPP property groups for now and keep it in the VS Code settings. However, as ZAPP profiles are intended to represent technology specific settings it might be possible to introduce a Zowe profiles profile (overloaded word) in the future. Will discuss with the team.

Some of your other ideas in that context, such as the use of a URL location type that would allow pointing to other Git repos or network resources directly (Issue 233) I still do find really interesting and something we should consider for property groups, as they are more technology independent.

[phaumer]

Z Open Editor 3.0.0 has now been released. Find this page now in the documentation here: https://ibm.github.io/zopeneditor-about/Docs/zopeneditor_v3.html

[FALLAI-Denis]

See ZOE 3.0.0 - Breaking change on zapp.yaml - Migration Automation

The sample provided here for new format of properyGroups and in Migrating from Z Open Editor v2 to v3 is not properly formatted.

[phaumer]

Thanks a lot. I fixed the indentation.

[FALLAI-Denis]

Hi,

For COBOL programs, in the propertyGroups structure of zapp.yaml, is the value assigned to the name property under the libraries property related to the name of the library in the COBOL directive: copy copyname in libraryname?

With the old zapp.yaml format, the name property probably had nothing to do with the copy directive's library-name.
With the new zapp.yaml format, the name property might have something to do with the library-name of the copy directive, and the given example referring to syslib suggests so.

Thus, one could limit the search for a copybook to only libraries whose name property corresponds to the library-name of the copy directive, (syslib as default), or even use the same names of copybooks in different libraries and select the correct copybook.

[phaumer]

@FALLAI-Denis yes, correct. See an example here: https://github.com/IBM/zopeneditor-sample/blob/main/COBOL/SAM1LIB.cbl
This one uses this property group that defines these library names and looks for file in different locations:

propertyGroups:
  - name: cobol-copybooks
    language: cobol
    libraries:
      - name: syslib
        type: local
        locations:
          - "**/COPYBOOK"
      - name: syslib
        type: mvs
        locations:
          - "IBMUSER.SAMPLE.COBCOPY"
      - name: MYLIB
        type: mvs
        locations:
          - IBMUSER.SAMPLE.COPYLIB
      - name: MYLIB
        type: local
        locations:
          - "**/COPYLIB-MVS"
      - name: MYFILE
        type: local
        locations:
          - "**/COPYLIB"

[FALLAI-Denis]

Hi @phaumer

Can there be an impact on the functioning of ZOE compared to the version indicated in the zapp.yaml file?

In zapp.yaml files we have indicated version 3.0.0 to refer to ZOE version 3.x.x.
The search for copybooks (at least remote copybooks on mvs) did not work...
We indicated version 1.0.0 in the zapp.yaml file, and the search for copybooks started working...

I can open an issue if necessary.

[phaumer]

@FALLAI-Denis that is very strange. The Version property in the ZAPP file is not used for anything. We added it so users can indicate with it the version of their application or use it for their own purposes. It can also be left out. It is not related to the schema version at all.

When a valid ZAPP file gets saved the editor restarts to reread all the settings. Perhaps something goes wrong during that restart? Check the log in the Output view. When the file has a syntax error or fails validation then an error is shown in the output and the editor is not restarted until is passes validation.

[FALLAI-Denis]

Hi @phaumer

I think something is wrong in the zapp.yaml file when starting ZOE and blocking the search for copybooks.

I think opening and saving zapp.yaml removes the error from the zapp.yaml file, even if the changed item in the zapp.yaml file is not the cause of the problem, and then ZOE can find copybooks.

I think it must be an encoding error (not utf-8?) or line ending sequence handling.
When zapp.yaml is saved, .gitattributes applies a fix for encoding and line ending handling.

What are the encoding and end-of-line sequence requirements on zapp.yaml files?

[phaumer]

Oh, we made the same assumptions as for json files that can only be utf encoded. The YAML spec also only focuses in that. https://yaml.org/spec/1.2.2/. Can you try converting the file in VS Code (using the status bar). I can do some more testing also for LFCR, but in the end I would like to only support UTF-8, really.