Merge branch 'dev' into dev

matthewpwilson · web-flow · commit c137e983808a · 2019-06-21T14:21:41.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -22,6 +22,38 @@ Please request new features via the issue tracker. When requesting features, try
 
 If you're thinking of fixing a bug or adding new features, be sure to open an issue first. This gives us a place to have a discussion about the work.
 
+### Setting up your development environment
+
+First of all, install Zowe CLI. Our plug-in is designed to work with the `lts-incremental` version.
+```console
+npm config set @brightside:registry https://api.bintray.com/npm/ca/brightside
+npm install @brightside/core@lts-lncremental
+```
+
+In order to make code changes to the cics-deploy plugin, you'll need to fork the repository, and build the plugin from source.
+
+```console
+git clone https://github.com/<your_github_id>/zowe-cli-cics-deploy-plugin
+cd zowe-cli-cics-deploy-plugin
+npm install
+npm run build
+zowe plugins install .
+```
+
+### Developing the cics-deploy plug-in
+
+As a plug-in for Zowe CLI, we aim to follow their guidelines. Our plugin is based on the Imperative CLI framework.
+
+| For more information about ... | See: |
+| ------------------------------ | ----- |
+| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and Plug-in Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)|
+| Guidelines for running tests on the plug-ins that you build for Zowe CLI | [Plug-in Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) |
+| Documentation that describes the features of the Imperative CLI Framework | [About Imperative CLI Framework](https://github.com/zowe/imperative/wiki) |
+
+As per the testing guidelines above, all code should have unit tests.  System tests should be written for cases where it's not necessary to interact with a remote CICS system. 
+
+Please make sure all tests pass before opening a PR. 
+
 ### Licensing
 
 All code must have an EPL v2.0 header.  Please add the following to any new files you create:
@@ -93,24 +125,20 @@ To save you having to type the above for every commit, Git can add the `Signed-o
 
 If you haven't signed each commit, then the pull request will fail to pass all checks.
 
-### Build and install the cics-deploy plugin
-```console
-git clone https://github.com/IBM/zowe-cli-cics-deploy-plugin
-cd zowe-cli-cics-deploy-plugin
-npm install
-npm run build
-zowe plugins install .
-```
+## Branches and releases
 
-## Developing Zowe CLI plug-ins
+We have three main branches in our repo:
+- *dev*: our main dev branch, which will work with Zowe CLI @lts-incremental. New pull requests should normally be made into this branch.
+- *master*: our release branch, which will work with Zowe CLI @lts-incremental. Project maintainers will merge code into here from `dev` when we're ready to release.
+- *zowe-dev*: a branch which works with Zowe CLI@daily so we can prepare for forthcoming major releases of Zowe CLI.
 
-For guidelines on developing Zowe CLI plug-ins see the [Zowe CLI GitHub repository](https://github.com/zowe/zowe-cli). The following information is critical to working with the code, running/writing/maintaining automated tests, developing consistent syntax and ensuring that the plug-in integrates with Zowe CLI properly:
+### Release process
 
-| For more information about ... | See: |
-| ------------------------------ | ----- |
-| General guidelines that apply to contributing to Zowe CLI and plug-ins | [Contribution Guidelines](https://github.com/zowe/zowe-cli/blob/master/CONTRIBUTING.md) |
-| Conventions and best practices for creating packages and plug-ins for Zowe CLI | [Package and Plug-in Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PackagesAndPluginGuidelines.md)|
-| Guidelines for running tests on Zowe CLI | [Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/TESTING.md) |
-| Guidelines for running tests on the plug-ins that you build for Zowe CLI | [Plug-in Testing Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/PluginTESTINGGuidelines.md) |
-| Documentation that describes the features of the Imperative CLI Framework | [About Imperative CLI Framework](https://github.com/zowe/imperative/wiki) |
-Versioning conventions for Zowe CLI and plug-ins| [Versioning Guidelines](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) |
+1. Ensure all code to be released is merged into `dev`.
+2. Create a release branch locally based on `master`.
+3. Merge commits to be relaased into the release branch. Avoid cherry-picking changes so that `master` always remains a subset of `dev`.
+4. Update the version number in `package.json` according to [semantic versioning](https://semver.org/). 
+   - Note: if the only changes being made are to the documentation, do not update the version number.  In this case the GitHub Pages site will be published when `master` is built, but no new version of the plug-in will be published.
+5. Make a PR to merge your release brnach into `master`. The reviewer should make sure all commits are suitable to release and version number has been updated appropriately. 
+6. After the PR is merged, Jenkins will run a build of `master` and publish the new version to registry.npmjs.org.
+7. Delete the release branch.
diff --git a/README.md b/README.md
@@ -4,16 +4,14 @@
 
 This project provides a plug-in for [Zowe CLI](https://github.com/zowe/zowe-cli) to deploy applications developed on a workstation to IBM CICS Transaction Server for z/OS (CICS). It aims to provide an experience similar to deploying to a cloud platform when deploying to CICS. It will also provide low-level commands for performing individual steps of the deployment process that could be used as part of a CI/CD pipeline.
 
-## Status
+## Installing
 
-The project was started in February 2019 and is at an early stage of development. It will initially focus on generating and deploying CICS bundles containing Node.js applications.
-
-To try it out, install the plug-in by following the steps in [installing](https://ibm.github.io/zowe-cli-cics-deploy-plugin/installing.html).
+Install the plug-in by following the steps in [installing](https://ibm.github.io/zowe-cli-cics-deploy-plugin/installing.html).
 
 ## Documentation
 
 You can find information and tutorials on using this plug-in in our [documentation](https://ibm.github.io/zowe-cli-cics-deploy-plugin/index.html).
 
 ## Contributing
 
-Contributions are welcome - see the [contribution guidelines](CONTRIBUTING.md). If you have a question or encounter a problem, please search the [issues](https://github.com/IBM/zowe-cli-cics-deploy-plugin/issues) in this repo before raising a [New issue](https://github.com/IBM/zowe-cli-cics-deploy-plugin/issues/new).
+Contributions are welcome - see the [contribution guidelines](CONTRIBUTING.md). If you have a question or encounter a problem, please search the [issues](https://github.com/IBM/zowe-cli-cics-deploy-plugin/issues) before raising a [New issue](https://github.com/IBM/zowe-cli-cics-deploy-plugin/issues/new).
diff --git a/docs/pages/cdp/cdp-Common-Errors.md b/docs/pages/cdp/cdp-Common-Errors.md
@@ -24,20 +24,25 @@ If you experience errors while using the cics-deploy plug-in, check the followin
 
 ### Application incorrectly deploys in a DISABLED state
 
-*Possible cause*: The port requested by the application is already in use.
+*Possible cause:* The port requested by the application is already in use.
 
-*Suggested action*: Choose a new port number after double-checking that it is not in use. Redeploy the application using the new value for the port.
+*Suggested action:* Choose a new port number after double-checking that it is not in use. Redeploy the application using the new value for the port.
 
 {% include note.html content="An application in a `DISABLED` state does not necessarily indicate an error condition. The `cics-deploy deploy`, `cics-deploy push` and `cics-deploy undeploy` commands allow you to specify a `--target-state` option which you may deliberately choose to set to `DISABLED`." %}
 
+### When deploying to multiple regions, the application fails to enable in the second and subsequent regions
+*Possible cause:* The application has deployed successfully in the first region, but subsequent regions see the requested port as in use, and cannot enable the application.
+
+*Suggested action:* Confirm the error by searching for `Error: listen EADDRINUSE :::30701` in STDERR. Contact a CICS systems administrator to set up port sharing for the affected port.
+
 ### Command error: DFHDPLOY stopped processing due to an error
 
-*Possible causes*:
+*Possible causes:*
 * The `--scope` and/or `--cicsplex` settings for the current deploy profile are wrong, and don't correctly identify a current CICS system, CICS System Group and/or a correct CICSPlex respectively.
 * The CMAS for the current CICSPlex is inactive.
 * CPSM is not functioning correctly.
 
-*Representative output*:
+*Representative output:*
 <pre class="messageText">
 16:22:50.058844 :  DFHDPLOY CICS TS APPLICATION DEPLOYMENT  2019/04/10 4:22pm
 16:22:50.059562 :  RELEASE: HCI7300.   SERVICE LEVEL: HCI7300.
@@ -47,16 +52,16 @@ If you experience errors while using the cics-deploy plug-in, check the followin
 16:22:50.065729 :  DFHRL2055I Errors have occurred, processing terminated.
 </pre>
 
-*Suggested actions*:
+*Suggested actions:*
 
 * Confirm that the `--scope` and `--cicsplex` settings are correct.
 * Ask your CICS Systems Programmer to check that the CMAS for the current CICSPlex is alive and that CPSM is working properly.
 
 ### Command error: ... validation of - -cicshlq dataset failed: z/OSMF REST API Error
 
-*Possible cause*: The profile setting for `--cicshlq` is incorrect.
+*Possible cause:* The profile setting for `--cicshlq` is incorrect.
 
-*Representative output*:
+*Representative output:*
 <pre class="messageText">
 A failure occurred during CICS bundle deployment.
 Reason = Validation of --cicshlq dataset failed: z/OSMF REST API Error:
@@ -69,21 +74,21 @@ details:
   - ISRZ002 Data set not cataloged - 'ANT.CICS.TS.DEV.INTEGRAT.SDFHLOAD' was not found in catalog.
 </pre>
 
-*Suggested action*: 
+*Suggested action:* 
 Check that your `--cicshlq` profile setting matches the value configured for CICS high-level qualifiers in your CICS region. 
 
 ### BUNDLE ... cannot be deployed (1)
 
-*Possible cause*: CICS does not have permission to read the bundle directory.
+*Possible cause:* CICS does not have permission to read the bundle directory.
 
-*Representative output*:
+*Representative output:*
 <pre class="messageText">
 11:46:15.916293 : DFHRL2300E BUNDLE(CICSJS02) cannot be deployed. The reason for the failure could not be determined.
 11:46:15.922147 : DFHRL2055I Errors have occurred, processing terminated.
 11:46:15.927066 : DFHRL2014I Disconnecting from CICSPLEX(CAPLEX).
 </pre>
 
-*Suggested action*: 
+*Suggested action:* 
 Check the MSGUSR file for more specific diagnostics and if relevant, change the permissions on the offending directory.
 
 <pre class="messageText">
@@ -93,9 +98,9 @@ DFHRL0110 E 04/24/2019 11:46:13 CALMAS1 COIE The CICS resource lifecycle manager
 
 ### BUNDLE ... cannot be deployed (2)
 
-*Possible cause*: The `cics.xml` file is malformed.
+*Possible cause:* The `cics.xml` file is malformed.
 
-*Representative output*:
+*Representative output:*
 <pre class="messageText">
 15:56:17.411714 :  DFHRL2300E BUNDLE(CICSJS02) cannot be deployed. The reason for the failure could not be determined.
 15:56:17.419308 :  DFHRL2055I Errors have occurred, processing terminated.
@@ -110,16 +115,16 @@ DFHRL0113 E 05/17/2019 15:56:15 CALMAS1 COIE The CICS resource lifecycle manager
            root directory. The manifest is not valid.
 </pre>
 
-*Suggested action*: 
+*Suggested action:* 
 Check that your `cics.xml` file is well-formed.
 
 ## General errors
 
 ### Syntax error: Invalid value length for option
 
-*Possible cause*: The length of the option you provided in a command was either too long or two short.
+*Possible cause:* The length of the option you provided in a command was either too long or two short.
 
-*Representative output*:
+*Representative output:*
 <pre class="messageText">
 Syntax Error:
 Invalid value length for option:
@@ -131,5 +136,5 @@ NODETESTS
 The length must be between 1 and 8 (inclusive)
 </pre>
 
-*Suggested action*:
+*Suggested action:*
 Review the error output text and reissue the original command having corrected the name of the option so that its length falls within acceptable limits.
