Create a Guide: Create a wiki for your project

[ExperimentsInHonesty]

Overview

We need to create a guide that shows how to use the Hack for LA GitHub template wiki to create a new wiki for your project's GitHub repository so that each project team can create a wiki for the project.

Action Items

• Gather examples of how other Hack for LA projects have done, adding each example as a link in the resources section
  • Once done, remove the "TG: Gather Examples" label and add the "TG: Draft Template" label
• Create a draft template, either in markdown format in this issue or a google doc in the product management google drive
  • Once done, remove the "TG: Draft Template" label and add the "TG: Create Guide" label
• Create a guide on how to use the template
  • Once done, remove the "TG: Create Guide" label and add the "TG: Review Guide" label
• Review the guide with product management communities of practice
  • Once done, remove the "TG: Review Guide" label and add the "TG: Leadership Review" label
• Present to Hack for LA leadership team for sign off
  • Once approved, remove the "TG: Leadership Review" label and add the "TG: Place Guide" label
• Possibly create an issue template on .github
  • Include link to template under resources if you add it as a template in .github

Resources

• Refer to Create a Guide/Template: How to Format A Guide knowledgebase-content#106 for how to write a guide and the guide template
• Update issue Tracker: Templates & Guides knowledgebase-content#104 with the name of item you are working
  Hack for LA's default repo wiki

To-do list

• Test it and indicate in the comments what is not working
• rewrite
• test again, repeat as necessary until working
• Add instructions to guide
  • Copy the wiki from the default repo
  • Customize the wiki for your project

Examples of good wikis
Design Systems
Civic Tech Index wiki
100 Automations wiki

[ExperimentsInHonesty]

@Olivia-Chiong has made a wiki, which I turned into a generic template and placed on the repo: https://github.com/hackforla.org/.github and we are in the process of documenting how to copy the wiki to a specific repo when you need it. Here is what Thad wrote for the Civic Tech Stucture BOP project. It still seems fairly incomprensible to me. We need someone who can document this a little more clearly. Possibly with screen shots. Might be worth asking Dean from 100 Automations to look at it, since he did it on that project.

Looks like my documentation comment got lost. This will have to do:

clone the brigade-playbook GitHub using ssh credentials, not HTTP
create a wiki page on brigade-playbook (or whatever new target)
git submodule add git@github.com:codeforamerica/brigade-playbook.wiki.git .github.wiki (substitute your repo name, do not copy it from the website)
git clone https://github.com/hackforla/.github.wiki.git hfla-github-wiki
copy all the files over to the e.g. brigade-playbook one in .github.wiki folder.
commit the files to brigade-playbook

[ExperimentsInHonesty]

Guide: Using the Hack for LA GitHub template wiki to create a new wiki for your project's GitHub repository

Hack for LA template repository and wiki

Step 1: Setup the wiki on your GitHub repository to receive the template files

Create a single page. You will be replacing it with the template so there is no need to customize it.

Step 2: Open up the command Line

Open the command line on your computer

On a Mac

1. click the command (⌘) + spacebar
2. Type Terminal and then enter key

On a PC

1. Download and unzip the thumbdrive version git
2. Open your Windows file explorer and locate the Git Bash application and open it.

Generate the SSH Key

3. In Git Bash type ssh-keygen press enter a few times to accept defaults (hardly anyone really has a passcode to their github SSH key, but you're welcome to make one.)
4. now type clip < ~/.ssh/id_rsa.pub

Follow instructions below on adding the key you have copied

• Before you begin, check to see if you have an ssh key: GitHub instructions
• If you don't have one, generate a new one using instructions above.

Go to your own GitHub profile and click Settings

Then choose

Click on the New SSH Key button

Input your key on the next screen

Step 3. Setup your local working directory

Change to a directory on your computer where you want to store the code

• Open a file explorer window and find or make a directory/folder where you want to place your work
• In the command line window type cd
• Drag the folder into the window
• Press enter

This image is from a windows machine, but it's basically the same thing with a MAC finder window.

Step 4. Get the wiki files from the template repository

any instructions that say type, are meant to be typed into the command line interface

Clone the template repository

type git clone git@github.com:hackforla/.github.git

Clone the destination repository

replace the brackets and the items in them with your information
customize and type git clone git@github.com:[name of your org/name of the repo].git

Change the directory to the name of the new destination directory that was created: [same as name of your repo]

type cd [name of the repo]

Get the wiki (a submodule) from your repo:

This is that same one you made when you setup the wiki initially (1st step).
customize and type git submodule add git@github.com:[name of your GitHub org/name of the repo].wiki.git .github.wiki

Open the local submodule destination folder that was just created.

type open .github.wiki on a Mac
type explorer .github.wiki on a PC
This will open a window on your computer with one file in it. Leave this window open so that you can copy the files to it later.

Navigate out of the destination directory

type cd ..

Clone the wiki files from the template repository

This will also create a directory called hfla-github-wiki
type git clone https://github.com/hackforla/.github.wiki.git hfla-github-wiki

Open the local folder where the template wiki files are going to go

type open hfla-github-wiki on a Mac
type explorer hfla-github-wiki on a PC
This will open a window on your computer. Leave this window open so that you can copy the files from it, after you have pulled them down.

Navigate into the folder

type cd hfla-github-wiki

Pull down all the files from the template wiki

type git pull
(you don't need to git pull if you just cloned)

Step 5. Manually copy the files from the two local folders you have opened

From the hfla-github-wiki window/folder to the .github.wiki window/folder

Navigate out of the folder

type cd ..

Step 6. Add the wiki to your GitHub repository

Navigate into the destination folder and then into the wiki submodule

type cd [same as name of your repo]
type cd .github.wiki

Add the files

type git add .

Commit the files

type git commit -m "upload the template wiki to the repo"

Push the files

type git push

Notes

• If you get lost and don't know which directory you are in, type pwd

• Before you commit, if this is your first commit, do:

  • type git config --global user.email "you@example.com"
  • type git config --global user.name "Your Name"

---

Notes about the commands used to setup the ssh. I looked on GitHub but their instructions were much more complicated and not specific to the message you would see.

$ ssh-keygen
$ cat /Users/bonniewolfe/.ssh/id_rsa.pub

[eselkin]

Prerequisite on Windows:

• Download and install git which includes git bash... There is a thumbdrive version of git bash so you don't need to install it on your machine!
• Make one change to the defaults that the install gives you:

... follow directions from github on making an SSH key
or:
in Git Bash type ssh-keygen press enter a few times to accept defaults (hardly anyone really has a passcode to their github SSH key, but you're welcome to make one.)
in Git Bash type clip < ~/.ssh/id_rsa.pub copy and follow instructions from github on adding the key you have copied

Step 2:

• On a PC, open your Windows/start menu and locate the Git Bash application and open it.
• Open a file explorer window and find or make a directory/folder where you want to place your work
• In the Git Bash window type cd then drag the folder into the Git Bash window (REPLACE the single quotes with new single quotes) then press enter
• git clone as above (make sure to type yes if it asks you to save the fingerprint)

On windows open doesn't exist, use explorer

• explorer .github.wiki
  ... then later...
• explorer hfla-github-wiki
• you don't need to git pull if you just cloned (one less step)

Should probably say somewhere, if you get lost and don't know which directory you are in, type pwd

Should be git add . not add .

Before you commit, if this is your first commit, do:

• type git config --global user.email "you@example.com"
• type git config --global user.name "Your Name"

Rest is good

[ExperimentsInHonesty]

on the mac version there needs to be some notes about what directory they are starting in, and how to list contents (ls), etc.

[ExperimentsInHonesty]

Prerequisite on Windows:

• Download and unzip the thumbdrive version git
• Open your Windows file explorer and locate the Git Bash application and open it.
• In Git Bash type ssh-keygen press enter a few times to accept defaults (hardly anyone really has a passcode to their github SSH key, but you're welcome to make one.)
• now type clip < ~/.ssh/id_rsa.pub

Follow instructions below on adding the key you have copied

1. Check to see if you have an ssh key: GitHub instructions
   1. If you don't have one, generate a new one: GitHub instructions

Go to your own GitHub profile and click Settings

Then choose

Click on the New SSH Key button

Input your key on the next screen

[ExperimentsInHonesty]

Prerequisite on Windows:

• Download and unzip the thumbdrive version git

Step 2:

• On a PC, open your Windows/start menu and locate the Git Bash application and open it.
• Open a file explorer window and find or make a directory/folder where you want to place your work
• In the Git Bash window type cd then drag the folder into the Git Bash window (REPLACE the single quotes with new single quotes) then press enter
• git clone as above (make sure to type yes if it asks you to save the fingerprint)

Note to add how to update the wiki if this is not the first download of the wiki template

• you don't need to git pull if you just cloned (one less step)

Should probably say somewhere, if you get lost and don't know which directory you are in, type pwd

Before you commit, if this is your first commit, do:

• type git config --global user.email "you@example.com"
• type git config --global user.name "Your Name"

[sayalikotkar]

Prerequisites:
The link to github asks you to check to see if you have SSH, but it requires you to have Git Bash in order to check

[Olivia-Chiong]

@sayalikotkar the instructions have been updated. Let me know if you are able to follow now.

[ExperimentsInHonesty]

Bonnie to talk to the 100 Automations team about making a automation out of this practice