Merge pull request #18 from cu-mkp/issue16

#16: adding how-tos from editioncrafter-data

how-tos/README.md

@@ -0,0 +1,9 @@
+## How-tos
+
+Because this repository may be used by beginners, a number of helpful how-tos have been included:
+- [command-line.md](command-line.md) - Command Line Intro and Helpful Commands
+- [github-local-setup-and-workflow.md](github-local-setup-and-workflow.md) - Setting up Github to Work Locally & General Workflow
+- [intro-to-github.md](intro-to-github.md) - Introduction to Git and Github
+- [naming-protocols.md](naming-protocols.md) - Naming Protocols
+- [project-setup.md](project-setup.md) - Project Setup Overview - reference for project developers
+- [tei-markup.md](tei-markup.md) - Overview of TEI file

how-tos/command-line.md

@@ -0,0 +1,76 @@
+# Introduction to using the command line
+
+-   For more info on bash: [<u>https://programminghistorian.org/en/lessons/intro-to-bash#opening-your-shell</u>](https://programminghistorian.org/en/lessons/intro-to-bash#opening-your-shell)
+
+    -   Contains information, tutorials, and commands
+
+-   Command: `man \[command, e.g., ls\]`
+
+    -   Brings up the manual for that particular command, showing its rules
+
+-   Command: `git status`
+
+    -   Lets you know the relative status of your local repo v the remote/origin
+
+-   Command: `git log`
+
+    -   Lets you see what’s been going on in Git recently
+
+-   Command: `df -h`
+
+    -   Checks how much free space you have on your computer
+
+-   Command: `ls`
+
+    -   Gives you a list of the folders/files in your current directory
+
+-   Command: `ls -la`
+
+    -   Gives you a list of ALL (even hidden) files in your current directory
+
+-   Command: `cd`
+
+    -   = change directory: helps you change directories
+
+    -   If you type “cd” with nothing after it, it will take you back to your home directory
+
+    -   If you type “cd” with the name of a parent or child directory relative to where you are, you will move to that directory
+
+    -   SHORTCUT: type “cd” and then the first character or two of your desired directory, then press \[tab\] and it will fill in the directory that matches the beginning of these characters
+
+        -   If this freezes, then there is more than one directory that begins the same way. Type another character or two so it is unique
+
+-   Command: `cd ..`
+
+    -   = go up a level in directories
+
+    -   `cd ../..` = go up 2 levels!
+
+-   Command: `less` \[filename of a file in your current directory\]
+
+    -   Allows you to see the file’s contents
+
+    -   NB: for filenames with spaces, precede each space with a backslash
+
+-   Command: `pwd`
+
+    -   = print working directory: tells you where you are (what directory you’re in)
+
+-   Command: `mkdir`
+
+    -   = make directory: create new directory
+
+-   Command: `mv` \[filename\] \[new filename\]
+
+    -   = move (but actually means rename the file)
+
+-   Command: `touch`
+
+    -   Creates a quick file
+
+-   DANGER: Command: `rm -f` \[filename\]
+
+    -   = remove, force (don’t ask questions or check if you’re sure)
+
+# For more information:
+-   For more info on working on the command line: [https://github.com/dh-notes/dhnotes/tree/master/tutorials/command-line](https://github.com/dh-notes/dhnotes/tree/master/tutorials/command-line)

how-tos/github-local-setup-and-workflow.md

@@ -0,0 +1,79 @@
+# Setting up Github to work locally & general workflow
+
+## Setting up Github
+The following three steps only need to be conducted once per machine or repository you are working with.
+### 1. Create a local workspace for Github repositories
+We recommend creating a dedicated directory for Github in your home user directory. For Windows, it is usually, for example, `C:\Users\naomi\Github`, and for Macs, for example, `/Users/naomi/Github`.
+
+### 2. Creating a private key to access your Github account
+SSH is a security protocol that enables computers to talk to each other using public key cryptography. Each user is required to have a private and public key pair to securely access your Github account when working from the command line. 
+
+To check if you already have this:
+1. In your home directory, type: `ls -la`
+2. Look for a directory called `.ssh`
+     a. If you have this directory, you already have a key
+     b. If you do NOT have this directory, you will need to make one.
+
+
+To make a new key, you will need to:
+1. Create a private/public key pair: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/
+2. Add it to your Github account: https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/
+
+### 3. Clone repository from Github (to make a local version)
+
+Once your key has been set up and linked, all you need to do is clone (which is like downloading) a copy of the repository to your local Githun directory you created in step 1 above. 
+
+You will need to copy the SSH address your repository - see [Cloning a Repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for a visual guide of where this is on the repo homepage. Make sure to grab the SSH one and not the HTTPS or GitHub CLI addresses. It should look something like `[email protected]:cu-mkp/editioncrafter-data.git`.
+
+In the command line, navigate to your Github directory, then do: `git clone [paste the SSH address here]`.
+For example, `git clone [email protected]:cu-mkp/editioncrafter-data.git`
+
+## Main workflow: setting up to work in a branch in a github project
+
+1. Create issue (or find one already created)
+2. Assign to someone (or yourself)
+3. Open the command line
+4. If you are using the Linux Subsystem for Windows, run the command:
+     1. `winhome`
+5. Navigate to the repository you want to work in, e.g., `m-k-manuscript-data`
+     1. For example, if this is where you start: `/mnt/c/Users/naomi/`, run the commands:
+     2. /mnt/c/Users/naomi/ `cd Github`
+     3. /mnt/c/Users/naomi/Github/ `cd m-k-manuscript-data`
+6. Pull the most updated version of the repository
+     1. `git fetch`
+     2. `git pull`
+7. Create new branch titled "issue[##]" (no spaces or special characters)
+     1. `git checkout -b [name of branch e.g. issue73]`
+8. Make edits to repository files (in text editors such as Sublime, oXygen, or in whatever program suits the files you are working with)
+9. Add file in local repository for tracking in github repository
+     1. `git add .`
+     2. `git commit -m '#[issue##]: [commit message]'` (this will ensure that this commit us linked to the issue you are working on)
+10. Push to the remote server (for the first time, MUST BE TRACKED)
+     1. `git push -u origin [branchname]`
+11. Submit a pull request in github interface (browser) to merge your issue branch with master
+     1. Go to the "pull request" tab where a message should appear asking if you would like to open a pull request
+     2. Another option: In branch dropdown menu, select the branch you want to merge, then hit the "new pull request"
+12. THC or NJR will merge the pull request unless there are conflicts to be resolved
+13. Close the issue
+14. `git checkout master` (= switch back to master branch)
+     1. `git checkout main` (master/main depending on the repository)
+
+## Other helpful commands
+
+- `pwd` "print working directory" -- tells you where you are in the command line
+- `ls` "list" -- tells you what files and folders are in the directory you are in
+- `cd` "change directory" -- this followed by the name of the directory or a path will move you to that directory
+- `cd ..` -- moves you up one directory
+- `less` [name of file] script reader
+- `q` "quit" -- exit out of a programming that is running
+
+## Check what branch you are in and make sure it is correct
+
+- See also [https://www.git-tower.com/learn/git/faq/checkout-remote-branch](https://www.git-tower.com/learn/git/faq/checkout-remote-branch)
+- _Navigate into the desired directory (i.e. m-k-manuscript-data)_
+- `git branch` _(tells you which branch you are in)_
+- `git fetch` _(tells you what is happening in remote repo)_
+- `git status` _(tells you which branch you're on and how far ahead or behind you are from Origin)_
+- If status is behind, pull the most current version
+     - `git fetch`
+     - `git pull`

how-tos/intro-to-github.md

@@ -0,0 +1,30 @@
+# Introduction to Github
+
+[Github](https://github.com/) is a hosting platform for software development that utilizes [Git](https://git-scm.com/), the open source system for distributed version control and source code management.
+
+Github allows large-scale and international collaboration on thousands of projects. While Git was originally intended for software development, it can be used in any collaborative working setup where maintenance of versioning is desirable.
+
+The Making and Knowing Project (M&K) has used Github for its versioning capabilities, project management tools, and as a way to share raw data and results openly. 
+
+## Create an Account
+
+Github is free to use, though there are certain advanced features that are only available behind a paywall. If you have an education email account (i.e., from a university or college), many of these advanced features are made free. Almost all (if not all) of the work we do is possible with a free Github account. 
+
+To get started, create a [Github account](https://github.com/) by signing up. You may want to use your education email account for added features, though this is not necessary. See [Getting started with your GitHub account](https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account) for more details.
+
+For an introduction of some of the main features of Github, we suggest reviewing [Github's Hello World Exercise](https://docs.github.com/en/get-started/quickstart/hello-world). Another useful resource is [W3schools' Intro to Github](https://www.w3schools.com/git/git_intro.asp?remote=github).
+
+## Repositories
+
+Each project in Github is housed in a respository, which contains all the files and directories (kind of like "folders" in your computer) of your project. 
+
+## Project Management Tools
+
+There are two main tools M&K has used to help organize and manage its Github activities.
+
+1. The Issue Tracker, found in each repository under the tab "Issues," is a place to help track work in the repository. Most often, an issue is a task or "to do" item, but it can also be used for things like tracking bugs, opening feature requests, or sharing ideas. Fore more information, see [About Issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues).
+2. Project Boards, found in each repository under the tab "Projects," is a place to organize issues and is very helpful for tracking in-progress, active, blocked, and completed issues. For more information, see [About Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) and [About "Classic" Projects](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards).
+
+## Markdown
+
+Markdown is the language used throughout Github and, as its name suggests, is a simplified markup language that allows you to style and format text and media, which converts readily to html, but is much easier to pick up and write with. See [Basic writing and formatting syntax in Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for details about how to format text (e.g., bold, italics, lists, headers, etc). See also [Programming Historian's Markdown Guide](https://programminghistorian.org/en/lessons/getting-started-with-markdown).

how-tos/naming-protocols.md

@@ -0,0 +1,31 @@
+_(last updated 2022-01-23)_
+
+# Introduction to File Naming Conventions
+
+Computers don't always know how to handle certain characters. Neither [Microsoft Windows](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx) or [Apple OSX](https://support.apple.com/en-us/HT202808) allow files to be named with special characters like questions marks `?` or slashes `\`. Special characters, spaces, and other elements are frequently reserved and possess meanings beyond the language we are speaking or typing. For example, periods `.` are used by operating systems to separate the descriptive file name from the extension (file type).
+
+Many standard services and servers, including those employed in creating our digital edition, function best with the guidelines outlined below and files named in a different way can create errors.
+
+The guidelines below describe general good practice for file naming in computing, but these names are not always the easiest to read or use in everyday personal computing.
+
+_For more general information about file naming conventions in computing, please see Purdue Libraries [Data Management for Undergraduate Researchers](http://guides.lib.purdue.edu/c.php?g=353013&p=2378293) which links to this clear guide: [Folder and File Naming Convention –10 Rules for Best Practice](http://www.exadox.com/en/articles/file-naming-convention-ten-rules-best-practice)._
+
+# Computing Guidelines
+
+- Use only alphanumeric characters (letters in the English alphabet + numbers)
+- Use all lowercase letters
+- Do not use spaces anywhere in your file's name
+- Do not use special characters such as: `! # $ % & ' @ ^ `` ~ + , . ; = ) ( "`
+  - No periods, commas, question marks, etc.
+- The only characters allowable other than alphanumeric characters are: hyphen/minus sign `-`, underscores `_`, and plus signs `+`
+- For spaces between words
+  - Use the hyphen/minus sign `-`
+  - Example: `painting-out-verdigris`
+- For spaces between elements (e.g. date, description, name, etc.) - _This is also known as an "element delimiter"_
+  - Use the underscore `_`
+  - Do not use spaces or other characters such as: `! # $ % & ' @ ^ `` ~ + , . ; = ) ( "`
+  - Example: `20160906_painting-out-verdigris` (date\_description)
+- Order your elements from general to specific
+  - This is most important for dates: Year, Month, Day
+  - (YYYYMMDD), (YYMMDD), (YYMM), etc
+  - Example: 20160906

how-tos/project-setup.md

@@ -0,0 +1,11 @@
+# Setting up Project in Github
+- Create new repository within [cu-mkp organization](https://github.com/cu-mkp) (by forking the [edition-crafter repo](https://github.com/cu-mkp/editioncrafter-data))
+- Add users and create teams
+- Open preliminary issues (including editing the read.me)
+- Edit read.me
+- Enable issues
+- Set up all users to clone repo locally 
+- Practice using the command line to add/edit the repo
+- Add text files
+- Introduce concept of tagging versions (v0.0.1, etc.)
+- Introduce Zenodo