Contributing to this guide

Anyone can update this guide as needed. Feel free to make live changes on this wiki, or for more substantial contributions, read on ...

Local Dev Setup

If you'd like to do some serious work on this guide, you may find it easier to work on your computer with a nice markdown editor. I've personally found MacDown to work well on the Mac.

1. Clone the debugging guide wiki repo to your local dev computer:

$ git clone [email protected]:bitmakerlabs/debugging-guide.wiki.git

2. install the gollum gem:

$ gem install gollum

3. You'll find that only committed changes show up in your browser. In order to always see your edits as you make them, setup Gollum Guard:

$ gem install guard guard-livereload

4. Install the livereload extension.

5. Open a terminal, change into the wiki folder, and run gollum:

$ gollum

6. Open a second terminal, change into the wiki folder, and run guard:

$ guard

7. With both gollum and guard running, click the livereload icon extension to activate it. You should see the little dot in the centre of the icon fill in. Now when you make a change, guard will commit the change and reload your browser.

8. You'll notice that gollum locally doesn't look exactly like gollum on github. This is okay. One thing you may want to do is disable the sidebar while you're working on it. To do this, just rename it:

$ mv _Sidebar.md temp_Sidebar.md

9. When you're finished working, make sure you rename the sidebar back to the usually name:

$ mv temp_Sidebar.md _Sidebar.md

10. Test

Ensure you test any changes on the actual wiki after push them from your development computer to github. There are many idiosyncrasies between how both gollum and the github wiki work.

Starting Menu

If you update the starting menu, it needs to be updated in three places:

• https://github.com/bitmakerlabs/debugging-guide
• https://github.com/bitmakerlabs/debugging-guide/wiki
• https://github.com/bitmakerlabs/debugging-guide/wiki/Bitmaker-Guide-To-Fixing-Bugs

Side Menu

If you add a new page or change a page's heading, update the side menu:

• https://github.com/bitmakerlabs/debugging-guide/wiki/_Sidebar/_edit

Links

When linking to this guide from within this guide, try to use just the page heading (i.e. your-page-heading) (i.e. not full paths), however, if the heading (which the link will be derived from) has a colon in it, you may need to use the full path (i.e. /bitmakerlabs/debugging-guide/wiki/your-page-heading).

Directories

I haven't been able to get directories working nicely with the Github wiki. Gollum supports this, but the Github wiki doesn't seem to (at least easily).