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.
GitHub is the primary mechanism for changes. Pull requests are the mechanism to submit and approve 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.
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.
The Harness Developer Hub is powered by Docusaurus. Larger changes should be vetted locally before submitting a PR.
- NPM
- 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.
:::note
The following instructions assume you run a Mac and have Homebrew installed:
:::
#Install node
brew install node
#Run
cd developer-hub
#Install Yarn
npm install --global yarn
#Validate installation
yarn --version
#Launch site
yarn
yarn start
#Access
http://localhost:3000
Harness follows the Microsoft Style Guide:
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. You can run Vale aganist a specific file or project structure.
#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
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
/tutorials
/verb
sometutorial.md
/static
/sometutorial
sometutorial.md
/somesubdtutorial
somesubdtutorial
/sub_catagory
somesubtutorial.md
Videos are great tools to embed. You can embed a video in your Markdown as the following:
<!-- Video:
https://harness-1.wistia.com/medias/rpv5vwzpxz-->
<docvideo src="https://harness-1.wistia.com/medias/rpv5vwzpxz" />
If possible, we would like to persist sample applications in a sample application repository. The sample application repository has a similar contributor's guide.
When adding a new Markdown file, above the initial H1 tag, a description is needed for SEO. Below is an example for a CI piece. Having keywords is recommended.
---
sidebar_position: 1
description: This build automation guide walks you through building a NodeJS and Docker Application in a CI Pipeline
keywords: [Hosted Build, Continuous Integration, Hosted, CI Tutorial]
---
Harness approvers will validate changes and approve the branch for merge into main. Once merged into main, the CI Process [Drone] will start automatically.
When PRs are filed, a preview environment is created for the Harness approvers to validate.
Please raise a Jira issue for non-content changes, such as infrastructure or UX ideas/changes before submitting a PR.