Update README and CONTRIBUTING

Signed-off-by: Matthew Wilson <[email protected]>

Author: matthewpwilson

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,19 @@ 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.
+4. 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. 
+5. After the PR is merged, Jenkins will run a build of `master` and publish the new version to registry.npmjs.org.

README.md

@@ -2,16 +2,19 @@
 
 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 use the cics-deploy plug-in, you'll first need Zowe CLI.
 
-To try it out, build the plug-in from source as described in [setup](docs-internal/tutorials/Setup.md).
+Then you can install the plug-in from the public npm registry by running the command
+```
+zowe plugins install zowe-cli-cics-deploy-plugin
+```
 
 ## 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).