Best practices and tips

Tag issues

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.
  • 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.

About DCO

"...technically every commit should be signed off as that is the idea behind DCO automation".

You can enable the DCO signoff tool https://github.com/coderanger/dco on 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 make commits directly in the GitHub UI, you still must paste your signature into the 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.