Best practices and tips

Tag issues and Pull Requests

It's a good practice to tag issues and Pull Requests with various labels to help you and Zowe PM more easily manage and track issues. When you open or noticed an issue in the doc repo, you can tag the issue as follows:

• Assign labels

  1. Add the Docs label to indicate that this is a documentation issue or has documentation impact.
  2. Determine which component or area the issue belongs to and select the appropriate component label from the Labels list.
  • apiml- Doc issue related to API Mediation Layer.
  • cli - Doc issue related to Zowe CLI.
  • web ui - Doc issue related to Zowe Application Framework, Zowe Desktop, or Zowe App Server.
  • zos services - Doc issue related to z/OS Services, Zowe REST APIs.
  • zowe explorer - Doc issues related to the VSCode extension "Zowe Explorer".
  • ci/cd - Issues for doc site, including doc site UX, automation, build etc.
  • misc - Used when you cannot determine which component or area one issue belongs to.
  3. (Optional) Determine if it's an enhancement or bug.
  • enhancement - New feature or request
  • bug - Doc defects such as broken links.
  4. (Optional) Add other labels that apply, for example, help wanted. For a list of labels, see https://github.com/zowe/docs-site/issues/labels.

• Assign a milestone

  If you know the target release for a doc issue, make sure to add the milestone for tracking purpose.

Editing files

Before making any changes/edits, go to GH Desktop and ensure your local repository is up to date: click Fetch origin and click Pull origin if you see that there are changes that you have not pulled (updated) in your local repository. This is indicated by a small notification dot with the number of upcoming changes.

To edit a topic, click on a file in the left navigation pane to open the file contents in the right editing pane. After finishing your updates, click Ctrl-S or File > Save to save your changes.

How to comment out text:  Enclose text with <!--xxx-->, where xxx is the text.

Syntax and CI/CD Rules

Make sure you adhere to the Markdown markup language syntax standards and linting rules. The Zowe Docs Jenkins CI/CD pipeline has several steps that contain quite rigid rules. Not adhering to these rules will result into a pipeline failure. Use the following rules for your reference:

• Ensure that your cross-references are correct. For example, if you change an .md file name, fix its name in all other files where it was referenced.
• Do not use a list item under the Level 1 # heading. You can use any ordered or unordered list under all other heading levels.
• If you want to include a static image or an animated image to your .md file, do not use the suggested syntax in the official Markdown cheat sheet. Use the <img src="your-gif.gif" alt=""> HTML tag instead.

About DCO

Every commit that you make in a Zowe GitHub repository must have a DCO signature. Pull Requests cannot be merged without meeting the DCO Status Check. For more information, see Developer Certificate of Origin (DCO).

Tips:

• You can enable this DCO signoff tool on your local PC if you don't want to copy/paste your signature in every commit manually. This works when committing via command-line or Github Desktop.
• If you commit directly in the GitHub web UI, you can install the DCO GitHub UI Chrome browser plugin. Configure the tool with the proper email address for "GitHub web-based operations" (you can find this in your GitHub email settings). If you have GitHub email security enabled, the email may look like [email protected]
• If you do not use these tools, you must manually sign off on every commit.

About branch and repo management

Periodically clean up unused branches and repos that you own.

Doc staging branch

https://github.com/zowe/docs-site/tree/docs-staging

• Hosts draft information for the next release. All content for the next new release should go to this branch instead of master branch before delivery.
• Remember to add release notes when a new feature or enhancement etc is made that has impact on user behavior
• Need to continuously sync updates from the master branch. You can understand the relationship between master branch and doc-staging as follows: docs-staging = master + new release content
• Copy over files to the master branch before delivery
• Can run local docs site to verify updates and do review. Need to educate your reviewer.