zowe / zlux

The top-level superproject for zLUX. zLUX includes the Zowe Desktop framework in addition to several built-in apps and an example server implementation.
Eclipse Public License 2.0
38 stars 42 forks source link

Review terminology in codebase and documentation #561

Open 1000TurquoisePogs opened 3 years ago

1000TurquoisePogs commented 3 years ago

Scan repos for terms in https://github.com/zowe/zlc/issues/199#issuecomment-727943937 to see existing coverage and potential problems.

1000TurquoisePogs commented 3 years ago

terminology.txt The following repos were scanned to produce this file

db-browser db-browser-db2 explorer-api-common explorer-jes explorer-mvs explorer-uss explorer-fvt-utilities explorer-ui-server file-transfer-app jupyter-app sample-angular-app sample-iframe-app sample-react-app tn3270-ng2 vt-ng2 workshop-starter-app workshop-user-browser-app zlux-app-manager zlux-app-server zlux-build zlux-editor zlux-file-explorer zlux-platform zlux-server-framework zlux-shared zlux-workflow zosmf-auth zowe-common-c zss-auth zss

1000TurquoisePogs commented 3 years ago

Breaking the results down by topic. Cases where our docs reference our branches, where branches are named master:

vt-ng2/README.md:This default can be changed, and is controlled by https://github.com/zowe/vt-ng2/blob/master/_defaultVT.json which is stored within the [configuration dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) at runtime.
vt-ng2/README.md:If you are running Zowe entirely on-mainframe, then the default host value of "localhost" is fine, but if you are running the zLUX server off-mainframe, then you will want to change this default when building the App, by editing \_defaultVT.json prior to deploying the App. [The App's deploy script](https://github.com/zowe/vt-ng2/blob/master/build/build.xml) can be invoked via running `ant deploy` in [zlux-build](https://github.com/zowe/zlux-build), in order to have this change take place.
zlux-app-manager/system-apps/app-generator/webClient/protractor.conf.js:// https://github.com/angular/protractor/blob/master/lib/config.ts
zlux-app-server/README.md:git submodule foreach "git checkout master"
zlux-app-server/README.md:Finally, the ZSS Cross memory server must be installed and configured according to [This Install Guide](https://github.com/zowe/docs-site/blob/master/docs/user-guide/install-zos.md#manually-installing-the-zowe-cross-memory-server)
workshop-user-browser-app/README.md:      https://github.com/zowe/workshop-starter-app/blob/master/webClient/src/app/workshopstarter-component.ts#L177
workshop-user-browser-app/README.md:  https://github.com/zowe/workshop-starter-app/blob/master/webClient/src/app/workshopstarter-component.ts#L225
tn3270-ng2/README.md:This default can be changed, and is controlled by https://github.com/zowe/tn3270-ng2/blob/master/_defaultTN3270.json which is stored within the [configuration dataservice](https://github.com/zowe/zlux/wiki/Configuration-Dataservice) at runtime.
tn3270-ng2/README.md:If you are running Zowe entirely on-mainframe, then the default host value of "localhost" is fine, but if you are running the zLUX server off-mainframe, then you will want to change this default when building the App, by editing \_defaultTN3270.json prior to deploying the App. [The App's deploy script](https://github.com/zowe/tn3270-ng2/blob/master/build/build.xml) can be invoked via running `ant deploy` in [zlux-build](https://github.com/zowe/zlux-build), in order to have this change take place.
1000TurquoisePogs commented 3 years ago

Cases where we have code comments or docs that use certain words

zlux-server-framework/lib/webserver.js:        //tls 1.3 was released in 2018, and tls 1.2 should be in this blacklist list when it has widespread support
explorer-ui-server/README.md:  -f, --csp             csp whitelist ancestors frames                       [required]
explorer-ui-server/src/index.js:  'csp': {key: 'f', args:1, description: 'csp whitelist ancestors frames', default:''},
1000TurquoisePogs commented 3 years ago

Outdated node name that can be updated zss/Jenkinsfile:node("ibm-jenkins-slave-nvm") {

1000TurquoisePogs commented 3 years ago

Instance where automation is pointing to a branch of ours named master explorer-api-common/build.gradle: requireBranch = 'master'

1000TurquoisePogs commented 3 years ago

Problem case 1: a sensitive word found in an api of a 3rd party library that does not have an alternative

zlux-app-manager/system-apps/app-generator/webClient/tslint.json:       "import-blacklist": [true],
zlux-app-manager/bootstrap/tslint.json:    "import-blacklist": [
zlux-app-manager/virtual-desktop/src/app/window-manager/mvd-window-manager/shared/window-manager.service.ts:  // We don't use windowID's here because each app lifecycle points to one master theme service, they're indistinguishable
zlux-app-manager/virtual-desktop/plugin-config/tslint.base.json:    "import-blacklist": [
zlux-app-manager/virtual-desktop/tslint.json:    "import-blacklist": [true, "rxjs"],
zlux-file-explorer/tslint.json:    "import-blacklist": [
zlux-platform/base/tslint.json:    "import-blacklist": [
zlux-workflow/webClient/tslint.json:    "import-blacklist": [

At best, we can migrate from tslint to typescript-eslint, which does not have 100% compatibility. This would be an problem to fix.

1000TurquoisePogs commented 3 years ago

Problem case 2: References to master branches that don't originate from our code

zlux-editor/webClient/protractor.conf.js:// https://github.com/angular/protractor/blob/master/lib/config.ts
zlux-editor/webClient/README.md:To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md).
zlux-server-framework/lib/webserver.js:        //in this file: https://github.com/openssl/openssl/blob/master/include/openssl/ssl.h
explorer-api-common/bootstrap_gradlew.bat:    powershell -Command "& {wget https://raw.githubusercontent.com/gradle/gradle/master/gradle/wrapper/gradle-wrapper.jar -OutFile gradle/wrapper/gradle-wrapper.jar}"
explorer-api-common/bootstrap_gradlew.sh:            https://raw.githubusercontent.com/gradle/gradle/master/gradle/wrapper/gradle-wrapper.jar

In some cases, removal or updates to documentation would resolve, but other cases here are direct links that can't just be changed.

1000TurquoisePogs commented 3 years ago

Problem case 3: Another 3rd party library which has a term in their API

sample-react-app/webClient/src/assets/i18n/i18n.js:  nonExplicitWhitelist: true,
sample-react-app/webClient/src/assets/i18n/i18n.js:  whitelist: ['en', 'ja', 'zh', 'de', 'fr', 'ru'],
1000TurquoisePogs commented 3 years ago

Problem case 4: Our rest api includes the term master, so we'd have to have a breaking change to get rid of it

zss/c/zosDiscovery.c:    addStringColumnInfo(p, "masterJobname", "MasterJobname", "Master Jobname", 5, 8);
zss/c/zosDiscovery.c:    addNumberColumnInfo(p, "masterASID", "MasterASID", "Master ASID", 4, 4);     /* should be hex */
zss/c/zosDiscovery.c:        jsonAddString(p, "masterJobname", NA_PROPRIETARY_INFO);
zss/c/zosDiscovery.c:        jsonAddInt(p, "masterASID", -1);
1000TurquoisePogs commented 3 years ago

Problem case 5: ZIS AUX has a notion of a master, so changing this will probably break vendor plugins that use it

zss/zis-aux/test/utils/src/shrmem64-test.c:  SHR64_PRINTF("info: master address space started, token = %016llX\n", token);
zss/zis-aux/test/address-space/README.md:  * The zis-aux/test/address-space/bin directory will contain a program called master
zss/zis-aux/test/address-space/README.md:  * Run master with parameters "start \<your-target-proclib-member-name\> \<your-parm-sting\>"
zss/zis-aux/test/address-space/README.md:  For example, ```  > ./master start ASTARGET test-parm-string```
zss/zis-aux/test/address-space/README.md:  * Run master with parameters "start \<your-target-proclib-name\> \<your-parm-sting\>"
zss/zis-aux/test/address-space/README.md:  * Run master with parameters "stop \<stoken-value\>"
zss/zis-aux/test/address-space/README.md:  For example,```> ./master stop 0000025C00000001```
zss/zis-aux/test/address-space/src/master.c:    printf("  > master start <start-string> <parameter-string>\n");
zss/zis-aux/test/address-space/src/master.c:    printf("  > master stop <stoken>\n");
zss/zis-aux/test/address-space/build/build.sh:# Build master
zss/zis-aux/test/address-space/build/build.sh:"-Wl,ac=1" -I $COMMON/h -I $ZSSAUX/src -I $ZSSAUX/include -o ../bin/master \
zss/zis-aux/test/address-space/build/build.sh:$ZSSAUX/test/address-space/src/master.c $COMMON/c/alloc.c $COMMON/c/as.c \
zss/zis-aux/test/address-space/build/build.sh:; extattr +a ../bin/master
zss/zis-aux/README.md:   * Handles communication with the cross-memory server (master)
zss/zis-aux/README.md: * AUX manager code - the code used by the master address space to:
zss/zis-aux/src/aux-host.c:    context->masterCommArea->flag |= ZISAUX_HOST_FLAG_READY;
zss/zis-aux/src/aux-host.c:    context->masterCommArea->flag &= ~ZISAUX_HOST_FLAG_READY;
zss/zis-aux/src/aux-host.c:    context->masterCommArea->flag |= ZISAUX_HOST_FLAG_TERMINATED;
zss/zis-aux/src/aux-host.c:    context->masterCommArea->flag &= ~ZISAUX_HOST_FLAG_TERMINATED;
zss/zis-aux/src/aux-host.c:  if (context->masterCommArea->parentASID == getSASN()) {
zss/zis-aux/src/aux-host.c:    context->masterCommArea->pcNumber = linkageIndex.pcNumber;
zss/zis-aux/src/aux-host.c:    context->masterCommArea->sequenceNumber = linkageIndex.sequenceNumber;
zss/zis-aux/src/aux-host.c:            ZISAUX_LOG_COMM_FAILED_MSG" master comm area parm not found");
zss/zis-aux/src/aux-host.c:            ZISAUX_LOG_COMM_FAILED_MSG" master comm area address string \'%s\' "
zss/zis-aux/src/aux-host.c:            ZISAUX_LOG_COMM_FAILED_MSG" master comm area %p has bad eyecatcher",
zss/zis-aux/src/aux-host.c:            ZISAUX_LOG_CONFIG_FAILURE_MSG, "master parms not read", readRC);
zss/zis-aux/src/aux-host.c:  context->masterCommArea = commArea;
zss/zis-aux/src/aux-host.c:  int masterParmRC = loadMasterParm(context);
zss/zis-aux/src/aux-host.c:  if (masterParmRC != RC_ZISAUX_OK) {
zss/zis-aux/src/aux-host.c:    return masterParmRC;
zss/zis-aux/include/aux-host.h:  ZISAUXCommArea *masterCommArea;
1000TurquoisePogs commented 3 years ago

Problem case 6: nodejs cluster api has a "master", so there will be occurrences when using that api. it's part of nodejs.

zlux-server-framework/lib/clusterManager.js:    /* We create the storage object at the master cluster. Each cluster will loop through
zlux-server-framework/lib/clusterManager.js:    and reference this master object, from any cluster */
zlux-server-framework/lib/clusterManager.js:    i. e. "if (this.storage) ..." since only the master cluster has storage */
zlux-app-server/lib/zluxArgs.js:  if (cluster.isMaster) {
zlux-app-server/lib/zluxArgs.js:    if (cluster.isMaster) {
zlux-app-server/lib/zluxArgs.js:    if (cluster.isMaster) {
1000TurquoisePogs commented 3 years ago

Other concerns: In-code variables which may or may not be part of our plugin apis, therefore may or may not break vendors plugins

zowe-common-c/h/le.h:  void **masterRTLVector; /* copied from CAA */
zowe-common-c/h/zos.h:  Addr31 cvtmslt;  /* master common area in master scheduler */
zowe-common-c/h/zos.h:  Addr31 cvtmser;  /* 0x94 addr of data area of master scheduler res data area */
zowe-common-c/c/le.c:  anchor->masterRTLVector = NULL; /* we don't have one of these, yet */
zowe-common-c/c/le.c:  anchor->masterRTLVector = caa->runtimeLibraryVectorTable;
1000TurquoisePogs commented 3 years ago

terminology.txt My original search was case sensitive, so I missed occurrences of things like Master. Here's the new file.

1000TurquoisePogs commented 3 years ago

Other code cases

explorer-api-common/explorer-api-common/src/main/java/org/zowe/api/common/security/SpringSecurityConfig.java:    private static final String[] AUTH_WHITELIST = {
explorer-api-common/explorer-api-common/src/main/java/org/zowe/api/common/security/SpringSecurityConfig.java:            .antMatchers(AUTH_WHITELIST).permitAll()
1000TurquoisePogs commented 3 years ago

Some end-user log messages:

zlux-server-framework/lib/assets/i18n/log/messages_en.json:  "ZWED0028I":"RESERVED: Master %s is running.",
zlux-server-framework/lib/assets/i18n/log/messages_en.json:  "ZWED0160W":"RESERVED: Master cluster not found to save storage for id: %s, value: %s",
zlux-server-framework/lib/assets/i18n/log/messages_en.json:  "ZWED0161W":"RESERVED: Master cluster not found to save storage",
zlux-server-framework/lib/assets/i18n/log/messages_en.json:  "ZWED0162W":"RESERVED: Master cluster not found to add storage",
zlux-server-framework/lib/assets/i18n/log/messages_en.json:  "ZWED0163W":"RESERVED: Master cluster was not found to delete storage for id: %s",