Contributing to the Knowledge Base

1. Set up Git

Download/install Git (if you don’t already have it)

https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
Get access to the modok repo. Scott will need to add you if you don’t have access yet.
If you haven’t worked with a repo yet, you will need to create an ssh key and add it to your bitbucket user profile.

https://support.atlassian.com/bitbucket-cloud/docs/set-up-an-ssh-key/
Open the Git bash app, and enter the following commands: git config --global user.name "firstname_lastname" git config --global user.email "[email protected]"
Close Git bash for now.

There are two branches that get built into knowledgebases:

The main differences are:

You can use the dev branch to work with reviewers if the raw markdown isn’t easy to read.

Before you start working directly in the dev branch in modok, it’s best to set up your own separate branch until you get used to working with git.

Create a new, empty folder
Open the folder, right-click and select Git Bash
git clone [email protected]:packetfabric/modok.git

You’ll be prompted for your ssh password
cd modok
git checkout -b <new branch name> e.g. git checkout -b caitlinrocks
Enter git status. It should show a message saying something like “working tree clean”.

Download and install Hugo:

https://gohugo.io/getting-started/installing/

Note - install the extended version. Not using the extended features right now, but have plans to in the future.
Open a command window from your new modok folder (created under step 2 above) and enter hugo server -D (the -D flag means that drafts are built. If you want to preview how it would look without drafts, just enter hugo server).
Open a browser tab to http://localhost:1313/. This is where you can view all your local work.

You’re ready to start working! Review the Writer’s Guide for a variety of ugly and hack-ish tips and tricks.

git status – shows what you’ve changed and what you can add
git add -A – will stage all your changes (meaning they will be included in your commit)
OR
git add content/<file path> – If you don’t want to stage all your files at once
git commit -m "<message saying what you're commiting>" - or whatever
You can do multiple commits before pushing, but when you’re ready to push to modok:

git push -u origin <branch name>

The basic process is:

1 - Checkout a branch.: You can think of a branch a copy of a folder. Say we were working out of a folder called “knowledgebase”, and you copied it and renamed it “knowledgebase2”. Then you start working on files within “knowledgebase2”.; To start with, it’s best to work in your own separate branch until you’re more familiar with our processes.
2 - Stage files.: When you stage a file, you are basically saying, “I want to save these changes and share them with everyone else working in knowledgbase2”
3 - Commit the staged files: Committing files is basically saving them. You can create a commit with just one file. You can create a commit with ten files – it’s just a batch save. But it creates a version snapshot of that file, and you can add a message explaining what you did, e.g. “Updated all the screenshots with color changes”
4 - Push changes: Up until now, all the work you’ve done and that commit only exist on your local computer. No one else can see them. Pushing changes saves them to the remote repository so that everyone can see your changes and incorporate them into their own work.

git checkout dev

git pull – Pulls down any changes that someone else may have made

git merge <localbranch> (if applicable)

You might get an annoying mesage about needing to commit. So just say something like:

git commit -m "Merge"

Then you can make more commits, push changes, etc.

When you are ready to push to master, it follows the same flow:

git checkout master
git pull
git merge dev
git push -u origin master
git checkout dev

Just get in there, merge dev, push the merge, and then go back to the dev branch

Updated on 12 Mar 2021