Turn On Notifications¶
In order to make use of the Handbook it's important that you are able to receive notifications from GitLab. Here are instructions on how to configure this:
Settingsfrom your profile drop-down at the top right of GitLab
User Settingsmenu on the left nav bar
- Confirm that the
Notification emailhas your @doublegdp.com email address
- Set the
Global notification levelto
- Confirm that all of the
Projectson the lower section of the page are set to
This will configure GitLab to send a notification email on all tasks and changes for which you are a participant or @mentioned, and it should be your default setting. You may modify these settings to better suit your preferences (instructions are available in GitLab documentation), but it is your responsibility to stay aware of requests made of you through GitLab.
Screenshot illustrating the proper notification settings...
Set up a local copy¶
You can contribute entirely through the online process above. However, you may also wish to set up a local copy of the handbook. This will make it easier to preview your changes and also gives you access to a few other writing tools that make it more user friendly. There's a bit more complexity to this process, but this guide should get you going.
To set up a local version of this handbook, you will need at least the following set up on your machine:
- Git -- see these installation instructions
- A Markdown editor -- we recommend Typora for a simple visual experience or Atom if you want an environment integrated with git.
- A local copy of the repository (instructions below)
This setup will be sufficient to make changes to the documentation, and is user-friendly for non-developers. You'll be able to see and contribute the files within the documentation, but won't have the same UI as on the website. If you want that full experience, you please install MkDocs.
Setting up Git¶
You will need to set your credentials in git. This may be a bit daunting at first, so we'll step through it together. Instructions are here
Git setup for Mac
From your terminal, run the following:
git config --global user.name "John Doe"
git config --global user.email "[email protected]"
Local copy of repo¶
To create a remote copy of the repository, open your terminal interface and navigate do the directory where you want to store it. (Nolan suggests
~/Projects.) Then run
git clone https://gitlab.com/doublegdp/handbook.git; this will create a
handbook directory that has the latest copy of the project.
Make your first edit¶
To make your first edit:
- In your terminal, run
- Open your markdown editor from the
docs/directory within the Handbook
- In your markdown editor, make a change and save it
- In your terminal run
git add .or
git add docs/name_of_changed_file.md
- In your terminal, run
git commit -m "Make first contribution"1
- In your terminal, run
If you want to run the handbook locally so you can see edits before committing, you also will need to set up your local environment to run mkdocs and other dependencies for the handbook. Setting up a local environment sometimes is easy and we'll outline the simple steps here. Unfortunately, complexities can sometimes arise based on other things in your environment; if this happens try Googling the error message and see if you can easily resolve it. If not, reach out for help!
The basics that you'll need are:
- Some installer -- we recommend Homebrew
- MkDocs -- try
brew install mkdocs
- Mkdocs Material theme -- try
pip install mkdocs-material
- Material Extensions -- try
pip install mkdocs-material-extensions
- Click Here to access your local copy of the Handbook.
Note that in order to do this, you will need to know a bit about how to use the command line within the
Terminal app (assuming you're using a Mac). Here's a quick primer.
Notes on updating / upgrading local environment¶
- Make sure to periodically update and upgrade
brew update && brew upgradethen
- Note that I first had to update all of my command line tools. (I don't remember the link to these instructions)
- In order to update brew, you may need to
git -C /usr/local/Homebrew/Library/Taps/homebrew/homebrew-core fetch --unshallow, which grabs the latest list of tools. Then I ran
brew upgrade. Based on the system's warning I also did
brew link --overwrite [email protected]
- Update mkdocs:
brew upgrade mkdocsfailed, so I ran
brew install mkdocs. This process also required
brew link --overwrite mkdocssince there was a previous version.
python3 -m pip install mkdocs-material
Updating local environment to run website¶
The website runs using Jekyll instead of MkDocs.
- Install rbenv:
brew install rbenv. Use Homebrew to install rbenv, but use rbenv to do the rest of the install.
- Install Ruby:
rbenv install 2.6.3then
rbenv global 2.6.3. Note that the website has dependencies that have not been updated in the latest version of Ruby; 2.6.3 is known to work.
- Install Jekyll:
gem install bundler jekyll. Doing this required
brew install openssl
bundle exec jekyll serve
- Click Here to access your local copy of our website.
This creates a 'commit' with a message. A
commitis an individual change to a set of files. Your message should be a brief and concise description of a simple change you're making to the docs. Make the first word of your commit message a verb, and use present tense. ↩