Skip to content

Latest commit

 

History

History
192 lines (125 loc) · 5.97 KB

CONTRIBUTING.md

File metadata and controls

192 lines (125 loc) · 5.97 KB
Raw

Contributing to Harness Developer Hub

CI CD FF CCM SRM STO IACM CE SEI CET IDP SSCA Code

Thanks for considering to contribute to the Harness Developer Hub! Contributions come in all shapes and sizes and we appreciate them all. Contributions to the Harness Developer Hub come in the form of creating pull requests or submitting issues.

Change process

GitHub is the primary mechanism for changes. Pull requests are the mechanism to submit and approve changes.

Small changes

Small changes are items that do not require local testing and can be accomplished in the GitHub UI, such as singular typo in an MD file.

Fixing Typos

Large changes

Large changes are considered to be an entire document/tutorial or making UI/UX changes such as to the site structure, organization, or branding. These changes require a fork and local development/testing.

Local development guide

The Harness Developer Hub is powered by Docusaurus. Larger changes should be vetted locally before submitting a PR.

  • NPM [Node 18 LTS]
  • Yarn

You need to fork this repository and create a branch to commit, which will be basis for the eventual PR . On your local machine, run the following commands.

ℹ️ Per the current version of Docusaurus, Node 18 LTS works the best. The following instructions assume you run a Mac and have Homebrew installed:

#Install node
brew install node@18
brew link node@18

#Run
cd developer-hub

#Install Yarn
npm install --global yarn

#Validate installation
yarn --version

#Launch site
yarn
yarn start

#Access
http://localhost:3000

Navigation and folder structure

Powering the left navigation are Docusaurus Sidbars. Update the sidebars.js file for new sections. For existing sections, certain sections are auto-generated by folder structure and certain landing pages are static.

/docs
	/module
		somedoc.md
		/static
			/somedoc
				somedoc.png
			/somesubdoc
				somesubdoc.png
		/sub_catagory
			somesubdoc.md

Videos

Videos are great tools to embed. You can embed a video in your Markdown as the following:



<!-- Video:
https://youtu.be/apSyBZCz5QA-->
<DocVideo src="https://youtu.be/apSyBZCz5QA" />

Sample applications

If possible, we would like to persist sample applications in a sample application repository. The sample application repository has a similar contributor's guide.

Markdown Tutorial

HDH is powered by Markdown. Take a look at a sample MD page showing off several MD features that are supported on HDH.

Additional metadata

When adding a new Markdown file, above the initial H1 tag, a description is needed for SEO. You can include optional keywords. For example:

---
title: NodeJS and Docker pipeline
sidebar_position: 1
description: This build automation guide walks you through building a NodeJS and Docker Application in a CI Pipeline
keywords: [Tutorial, Continuous Integration, NodeJS, Docker]
---

keywords are only available in the page metadata. They are not rendered when published.

tags are similar to keywords; however, they offer interactive functionality. If included, tags appear at the bottom of the page. Selecting a tag directs the user to a page listing all pages with that tag. Only use tags if they are used holistically; otherwise the use of tags creates pages with only a few links, rather than accurately representing the full offering of thematically-related content.

---
title: NodeJS and Docker pipeline
sidebar_position: 1
description: This build automation guide walks you through building a NodeJS and Docker Application in a CI Pipeline
tags: [Tutorial, "Continuous Integration", NodeJS, Docker]
---

Change approval flow

Harness approvers will validate changes and approve the branch for merge into main. Once merged into main, the CI Process [Harness CIE] will start automatically.

PR preview environment

When PRs are filed, a preview environment is created for the Harness approvers to validate.

Non-content changes

Please raise a Jira issue for non-content changes, such as infrastructure or UX ideas/changes before submitting a PR.

Archived Information

Additional info that might not be prudent to your first contribution.

Style guide

Harness Documentation follows the Microsoft Style Guide. We would recommend this.

Since the final document is in Markdown, feel free to author in a tool of your choice and port to Markdown.

Vale is an excellent tool for validating spelling and style in Markdown locally. You can run Vale aganist a specific file or project structure prior to submitting if you would like, locally. This is not required.

ℹ️ Part of the PR checks, we are currently not using Vale. If you would like to check locally/programatically, Vale is a good tool.

#install
brew install vale

#Create Vale INI
#https://vale.sh/docs/vale-cli/structure/#valeini

cat <<EOF >>.vale.ini
StylesPath = styles

MinAlertLevel = suggestion
Vocab = Base

Packages = Microsoft, write-good

[*.md]
BasedOnStyles = Vale, Microsoft, write-good
EOF

#Vale sync
vale sync

#Execute Vale
#cd into parent local folder if you want to validate all files.

vale ./developer-hub/docs/**/*.md