Zowe-Install-Packaging repo documentation

.github/workflows/link-check-pulls.yml

@@ -0,0 +1,21 @@
+permissions: read-all
+
+name: Check Markdown Links - PR
+
+on:
+  push:
+    branches-ignore:
+      - 'v2.x/*'
+      - 'v1.x/*'
+  pull_request:
+    branches:
+      - '**'
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+
+    - uses: gaurav-nelson/github-action-markdown-link-check@d53a906aa6b22b8979d33bc86170567e619495ec # v1.0.15

.github/workflows/link-check-weekly.yml

@@ -0,0 +1,23 @@
+permissions: read-all
+
+name: Check Markdown Links - Weekly
+
+on:
+  push:
+    branches:
+    - 'v2.x/master'
+    - 'v2.x/staging'
+    - 'v1.x/master'
+    - 'v1.x/staging'
+  schedule:
+  # Every day @ 4 AM
+  - cron: "0 4 * * *"
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2
+
+    - uses: gaurav-nelson/github-action-markdown-link-check@d53a906aa6b22b8979d33bc86170567e619495ec # v1.0.15

CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# Contribution Guidelines
+This document is a living summary of conventions and best practices for development within the zowe-install-packaging repository.
+
+  - [SIGN ALL OF YOUR GIT COMMITS](#sign-all-of-your-git-commits)
+  - [Understanding the Repository](#understanding-packages-and-plug-ins)
+  - [Pull Requests](#pull-requests)
+  - [General Guidelines](#general-guidelines)
+  - [Changelog Update Guidelines](#changelog-update-guidelines)
+  - [Code Guidelines](#code-guidelines)
+  - [Versioning Guidelines](#versioning-guidelines)
+  - [Build Process Guidelines](#build-process-guidelines)
+  - [Documentation Guidelines](#documentation-guidelines)
+  - [More Information](#more-information)
+
+## SIGN ALL OF YOUR GIT COMMITS
+
+Whenever you make a commit, it is required to be signed. If you do not, you will have to re-write the git history to get all commits signed before they can be merged, which can be quite a pain.
+
+Use the "-s" or "--signoff" flags to sign a commit.
+
+Example calls:
+* `git commit -s -m "Adding a test file to new_branch"`
+* `git commit --signoff -m "Adding a test file to new_branch"`
+
+Why? Sign-off is a line at the end of the commit message which certifies who is the author of the commit. Its main purpose is to improve tracking of who did what, especially with patches.
+
+Example commit in git history:
+
+```
+Add tests for the payment processor.
+
+Signed-off-by: Humpty Dumpty <[email protected]>
+```
+
+What to do if you forget to sign off on a commit?
+
+To sign old commits: `git rebase --exec 'git commit --amend --no-edit --signoff' -i <commit-hash>`
+
+where commit hash is one before your first commit in history
+
+If you forget to signoff on a commit, you'll likely receive the following message:
+
+"Commit message must be signed off with your user name and email.
+To sign off your commit, add the -s flag to the git commit command."
+
+## Understanding the Repository
+
+The zowe-install-packaging repository contains multiple sub-projects written in different languages with different goals. To better understand the repository structure and intent behind each sub-project, visit the [repository overview](./docs/README.md).
+
+## Pull Requests
+
+Consider the following when you interact with pull requests:
+
+- Pull request reviewers should be assigned to a member of the Zowe Systems Squad or a member of your Zowe component squad. See [points of contact](./README.md#point-of-contacts).
+- Pull requests should remain open for at least 24 hours, or until close of business next business day (accounting for weekends and holidays).
+- Anyone can comment on a pull request to request delay on merging or to get questions answered.
+- Any exception to the above should be mentioned in the pull request, either in the pull description or as a comment.
+
+## General Guidelines
+
+The following list describes general conventions for contributing to zowe-install-packaging:
+
+- Communicate frequently (before pull request) with cross-team member representatives (in informal & small meetings) for new design features.
+- Before implementing new functionality, evaluate if existing packages or functions available already achieve intended functionality.
+- Provide adequate logging to diagnose problems that happen at external customer sites.
+
+## Changelog Update Guidelines
+
+Add an entry to changelog.md for any PR that introduces a feature, enhancement, or fix that affects end users. Changes to certain files, such as Github Workflows, do not require a changelog update. The changelogs are compiled into Zowe Docs [Release Notes](https://docs.zowe.org/stable/getting-started/summaryofchanges.html) periodically.
+
+**Each changelog entry must:**
+- Describe the change and how it impacts end users.
+- Include a relevant Issue # or Pull Request #.
+
+The following is an example of the markdown that you should insert into the changelog above the last-released version:
+
+```
+## Recent Changes
+
+- Document your changes here. [Issue# or PR#](link-to-issue-or-pr)
+- Document another change here. [Issue# or PR#](link-to-issue-or-pr)
+```
+
+**Tips:**
+- Start the sentence with a verb in past tense. For example "Added...", "Fixed...", "Improved...", "Enhanced...".
+- Write from a user's perspective. Document why the change matters to the end user (what this feature allows them to do now). For example, "Added the validate-only mode of Zowe. This lets you check whether all the component validation checks of the Zowe installation pass without starting any of the components.".
+- Use second person "you" instead of "users".
+
+## Code Guidelines
+
+Indent code with 2 spaces. This is also documented via `.editorconfig`, which can be used to automatically format the code if you use an [EditorConfig](https://editorconfig.org/) extension for your editor of choice.
+
+As there are multiple languages in this repository, coding guidelines can only be stated in generalities for the entire repository. Above all, aim to make code readable and obvious rather than clever or succinct. Optimize for the maintainer of the future who is less familiar with your area of expertise.
+
+## Versioning Guidelines
+
+For information about adhering to our versioning scheme, see [our versioning strategy](./docs/dead_link-versioning.md).
+
+## Build Process Guidelines
+
+Use build tasks to enforce rules where possible.
+
+## Documentation Guidelines
+
+- For **all user-facing contributions** (i.e. HOLDDATA or `zwe` command-line changes), we recommend that you provide the following:
+
+   - A Release Notes entry in [Zowe Docs site](https://github.com/zowe/docs-site) to announce your change to end users.
+   - Documentation for how to use your feature, command, etc... Open an issue in [docs-site repository](https://github.com/zowe/docs-site) if you need assistance.
+
+In addition to external documentation, please thoroughly comment your code for future developers.
+
+## More Information
+| For more information about ... | See: |
+| ------------------------------ | ----- |
+| Branch Strategy | [Documentation](./docs/README.md#branch-strategy) |
+| Repository Overview | [Documentation](./docs/README.md) |

README.md

@@ -1,104 +1,36 @@
 # zowe-install-packaging
 
-This repository includes Zowe installation script and pipelines to build Zowe.
+This repository includes automation, artifacts, and scripts which are used to create the final set of Zowe installable artifacts for the Zowe server side. This repository additionally contains metadata used to track official Zowe releases across multiple build pipelines.
 
-- [Branches](#branches)
-- [Manifest File](#manifest-file)
-  - [General information](#general-information)
-  - [Build information](#build-information)
-  - [Binary Dependencies](#binary-dependencies)
-  - [Source Dependencies](#source-dependencies)
-  - [Point of Contacts](#point-of-contacts)
-- [Build Pipeline](#build-pipeline)
-  - [Generate Customized Zowe Build](#generate-customized-zowe-build)
-- [Automate Install / Uninstall of Zowe with Ansible](#automate-install--uninstall-of-zowe-with-ansible)
-- [Quick Sanity Check on Your Zowe Instance](#quick-sanity-check-on-your-zowe-instance)
+- [Contributing](#contributing)
+- [Building](#building)
+- [Running Zowe](#running-zowe)
+- [Points of Contact](#point-of-contacts)
 
-## Branches
+## Contributing
 
-- From `master` branch, you can find the most recent **stable** build. It matches to the most recent official Zowe release.
-- `rc` branch means release candidate and is mainly for release usage. It's an intermediate state where we hold the code to prepare for the coming release. This branch is merged from `staging` and eventually if Release Candidate builds are tested passed, this branch will be merged into `master` to announce a formal release.
-- `staging` branch is targeted to the next release and holds the most recent development progress. Normally a development changes may result in a Pull Request against this branch.
-- `v?.x/*` branches are for past and future purpose. It may also have `v?.x/master` and `v?.x/staging`, etc.
+To contribute to this repository, please follow the [contributing guidelines](./CONTRIBUTING.md).
 
-Pull Request is required to merge changes to `staging`, `rc`. Generally `master` doesn't accept Pull Request to make feature changes or bug fixes.
+## Building
 
-## Manifest File
+Zowe-Install-Packaging is composed of multiple sub-modules and directories which drive the aggregation of individual Zowe components into a final distributable package users can take to install on their mainframe systems. This repository contains pipeline definitions, pipeline implementation details, simple component provenance information, scripts which improve the install and configuration of Zowe, test suites, and more artifacts related to the final package formats. There is no individual build for the entire repository, but instead multiple related builds that require different aspects of the repository. To see more about these builds, check our Github Actions definition [here](./.github/workflows/). To see more about whats in the repository, see [our repository doc](./docs/README.md). To verify code changes, open a PR and request a review from one of the contact points below.
 
-Zowe include several components. `manifest.json.template` defines general information of Zowe and how components are included into official build.
+## Running Zowe
 
-The manifest file include these sections:
+For information on running Zowe, see [the Zowe quickstart guide](./ZOWE.md).
 
-### General information
-
-These information are represented in these properties: `name`, `version`, `description`, `license` and `homepage`.
-
-### Build information
-
-These information includes details when building the Zowe artifact. During build process, `manifest.json.template` will be converted to `manifest.json` and the template variables like `{BUILD_COMMIT_HASH}` will be filled in with real value. The modified `manifest.json` will be placed into root folder of Zowe build.
-
-Here is an example of build information after build, you can find it in the `manifest.json` file from every Zowe build:
-
-```
-  "build": {
-    "branch": "staging",
-    "number": "202",
-    "commitHash": "dad00f0a9c45f34bfbe3ec56a8443f2e818e59f4",
-    "timestamp": "1568205429441"
-  },
-```
-
-The above build information means this Zowe build is from `staging` branch build #202, git commit hash is [dad00f0a9c45f34bfbe3ec56a8443f2e818e59f4](https://github.com/zowe/zowe-install-packaging/commit/dad00f0a9c45f34bfbe3ec56a8443f2e818e59f4). Build time is `1568205429441`, which means `Wed Sep 11 2019 08:37:09 GMT-0400 (Eastern Daylight Time)`.
-
-### Binary Dependencies
-
-`binaryDependencies` section defines how many components will be included into the binary build. Each component has an unique ID, which hints where the pipeline should pick up the component artifact. Also for each the component, it defines which version will be included into the build.
-
-Here is an example of component definition:
-
-```
-    "org.zowe.explorer.jobs": {
-      "version": "~0.2.8-STAGING",
-      "explode": "true"
-    }
-```
-
-`org.zowe.explorer.jobs` is the component ID, which also tell the pipeline to pick the component from Artifactory path `<repo>/org/zowe/explorer/jobs/`. `version` defines which version we should pick. In this case, we should pick the max version matches `0.2.*-STAGING` and `>= 0.2.8-STAGING`. So version `0.2.10-STAGING` is a good match if it exists.
-
-For details of **how to define a component**, please check examples and explanations from https://zowe.github.io/jenkins-library/jenkins_shared_library/artifact/JFrogArtifactory.html#interpretArtifactDefinition(java.lang.String,%20java.util.Map,%20java.util.Map).
-
-### Source Dependencies
-
-`sourceDependencies` section defines how the component binary matches to the Zowe github repository, branch or tag. It is grouped by `componentGroup`. For example, `Zowe Application Framework` componentGroup includes all repositories related it and listed in `entries` section.
-
-One example component entry looks like:
-
-```
-  {
-    "repository": "imperative",
-    "tag": "v2.4.9"
-  }
-```
-
-This means the Zowe build is using https://github.com/zowe/imperative repository tag [v2.4.9](https://github.com/zowe/imperative/tree/v2.4.9).
-
-**Please note, this section may not reflect the correct value for non-formal-release.** Only for formal releases, we will update these sections to match the correct repository tags.
-
-To check for each release, what source code from repositories will be used, you can:
+### Point of Contacts
 
-- go to https://github.com/zowe/zowe-install-packaging,
-- click on [?? releases](https://github.com/zowe/zowe-install-packaging/releases),
-- find the release name. For example [v1.4.0](https://github.com/zowe/zowe-install-packaging/releases/tag/v1.4.0),
-- click on the tag name on the left. In the above case, it shows [v1.4.0](https://github.com/zowe/zowe-install-packaging/tree/v1.4.0),
-- find and check file `manifest.json.template`. In the above case, it links to [v1.4.0/manifest.json.template](https://github.com/zowe/zowe-install-packaging/blob/v1.4.0/manifest.json.template).
-- check the `sourceDependencies` section. In the above case, it's line #96.
-- In the above example, you will see Zowe release v1.4.0 is using https://github.com/zowe/imperative repository tag [v2.4.9](https://github.com/zowe/imperative/tree/v2.4.9).
+For submitting code changes unrelated to a Zowe component update, please contact one of the below:
 
-### Point of Contacts
+- Mark Ackert
+- OJ Celis
+- Sean Grady
+- James Struga
 
-For each Zowe component, we have point of contact(s) in case if we want to confirm the versions defined in the `manifest.json.template`:
+For each Zowe component, we have point of contact(s) in case if we want to confirm the versions defined in the `manifest.json.template`. For more information on the `manifest.json`, see the [repo overview](./repos/overview.md):
 
-- API Mediation Layer: Elliot Jalley, Mark Ackert
+- API Mediation Layer: Elliot Jalley, Jakub Balhar, Mark Ackert
   * Binary Dependencies
     - org.zowe.apiml.sdk.zowe-install
   * Source Dependencies
@@ -164,31 +96,3 @@ For each Zowe component, we have point of contact(s) in case if we want to confi
 - License: Mark Ackert
   * Binary Dependencies
     - org.zowe.licenses
-
-## Build Pipeline
-
-Zowe build pipeline has hooked into github repository. Every branch, commit and PR has potential to kick off a new Zowe build. If the build is not automatically started, you can go to Jenkins and start a build job on the appropriated branch or pull request.
-
-### Generate Customized Zowe Build
-
-If your changes are in `zowe-install-packaging`, you may already have a Zowe build if you have a branch. Otherwise you will have one if you create a pull request on your changes.
-
-If your changes are in components, it may depend on how the Zowe build picks your changes:
-
-- If you have released, or have a snapshot build of your component, very likely the change will be picked up by the `staging` branch build. If not, you need to check the `binaryDependencies` section in `manifest.json.template`.
-- If your changes is still in a branch of the component repository, you can edit `manifest.json.template` to use the branch build directly like this:
-
-  ```
-    "org.zowe.explorer.jobs": {
-      "artifact": "lib-snapshot-local/org/zowe/explorer/jobs/0.2.7-MY-BRANCH-BUILD.zip",
-      "explode": "true"
-    },
-  ```
-
-## Automate Install / Uninstall of Zowe with Ansible
-
-Please check details in [playbooks folder](playbooks/README.md).
-
-## Quick Sanity Check on Your Zowe Instance
-
-Please check details in [sanity test folder](tests/sanity/README.md).