# Contribution Guide to the Docs

As this is a technical documentation the change process is rather technical as well, but therefore solid as it's build upon common development practises. It involves a Version Control software called Git and something that's called NodeJS. Overwhelmed? Don't be. This guide is going to show you how to work with all of that in "3 Easy Steps".

# Getting Started

# Prerequisite

You have access to the Azure Devs Repository which hosts the sources for this website. Click on "Contribute (opens new window)" in the menu bar on the far right to find out if you already have access.
You have installed and configured Git
You have a running NodeJS installation
You have a text editor other than notepad.exe to edit the files. Recommendation: VSCode (opens new window)

# Obtain the docs sources

We now can use git to clone the sources from the Azure Repository to get a local copy. After that we can point our shell to the cloned repo with cd (change directory).

git clone git@ssh.dev.azure.com:v3/giffits/Documentations/Internal-Documentations
cd Internal-Documentations

# Install dependencies

As we only store our sources but this project involves third party dependencies, we need to install those.

npm install

# Test installation

Now would be a good moment to test if every thing worked out so far. Run the following command to start a local test instance.

npm run serve

Open http://localhost:8080 (opens new window) in your Browser. You should see you copy of the docs now. You can open up the shell window in which the command above is running and exit the process at any point with crtl + c

# Workflow

To ensure that our documentation stays at a high quality level we implemented a workflow which includes approval of any change made to the live website. https://internal.docs.giffits.de (opens new window)

# Step #0

You should have already done this step if you worked through the Getting Started section. Move on to Step #1. If not, please follow the Getting Started Section.

# Step #1 - Create a new branch

Make sure you are on the master branch and it is up to date.

git checkout master
git pull

Then create a new branch from master we can commit our changes to.

git checkout -b feature/my-super-important-change

TIP

Branches are a great way to separate your work from other until you want to publish them by "merging" them to the master branch.

# Step #2 - Changing the docs

Start the documentation page locally as we already did in out little installation test.

npm run serve

Open http://localhost:8080 (opens new window) in your Browser. You can start editing the .md files in the src folder and the website should update automatically while you do so. When you are happy with you changes exit the local instance with crtl + c and move on to Step #3.

# Step #3 - Publishing you changes

# Publishsing changes to git

To publish your changes you need to commit and push them to the Azure git repository first. Execute the following commands:

git add -A

Adds the changed files to be commited in next commit.

git commit -m 'feat: added an awesome page about 0 and 1'

Commits the changes to your local copy of the git repository. (Please write something useful instead of my awesome changes)

git push

Uploads the changes to the Azure Git Repository.

# Creating a Pull request

Head over to the Azure DevOps portal (opens new window) and create a pull request from you branch to master. Add a useful title and description that tell the reviewers we will select next what the intentions of you changes are. Add at least one colleague whom is able to review and understand your changes as a reviewer. And finally create the PR.

# Approval and merging

At this point it would be wise to contact the colleagues selected for review. They need to Approve the PR or make comments for you to improve your changes. One approved changes can be merged and will be automatically released and deployed after that. To do so press the "Complete" button in the upper right corner. Do not forget to overwrite the commit message at this point. There is a option for that after clicking the "Complete" button. We use Conventional Commits to describe the changes made. This ends up in the changelog of the documentation so you might want to put something descriptive there. The idea of conventional commits is mainly used to describe software changes but we can translate this to documentation changes just fine.

Examples:

Task	Message
Fixing a typo	`fix: Fixed Typo in Service Documentation XY`
Adding a page	`feat: Added installation guide for Service XY`
Rewriting a page	`refactor: Enhanced documentation for Service XY`

Congratulations! 🎉

You've just published your first change to the documentation. It will be live after about 10 minutes.

← Home AWS →