Computational Syntax: Playground Repository

Overview

This is the playground repository for Computational Syntax (Lin 628), offered by the [Department of Linguistics] department at [Stony Brook University] sbu.

This is a private repository where you can safely work collaboratively on the lecture notes.

Repository Structure and Workflow

The repository has a number of branches:

1. raw contains the source code for units pulled straight from the main repository. Whenever a new unit is uploaded to the main repository, the student with role master pushes it into the raw-branch of this repository.
2. There is a number of feature-branches, e.g. tikz, examples, and so on. In each branch, one or more students work on a specific aspect of the lecture notes. Once they consider a task done, they file a push request against the branch draft.
3. The student with role master approves push requests and merges them into draft. He or she also compiles a pdf version of that unit. If compilation fails, the master contacts the students whose pull request created the problem and asks them to fix their code.
4. The reader and the editor read the draft version and jointly decide how to proceed: is the unit good as is, does the existing material need revisions, or is crucial material missing? Stylistic revisions and minor additions are handled by the editors in the editorial branch (with a subsequent pull request against draft), major changes have to be made by the students working on the relevant feature. (Never work directly on files in draft! It will make it much harder to resolve merge conflicts during pull requests.)
5. Once a draft version has full approval from the reader and the editor, the master merges it into the master branch.

Team Roles

• Hammer: quickly hammers out a rough draft that indicates the overall structure and content of the unit; this includes

  • splitting the content into sections,
  • inserting (rough versions of) definitions, theorems,
  • indicating what examples, figures and tables need to be created,
  • adding some very basic text to link all of that together. Imagine a bullet-point handout where complicated typesetting is left to another party.

• Sandpaper: takes the output produced by the hammer and sands off the rough edges; this includes

  • complete prose text as in a textbook, but without particular attention to style, spelling, or grammar
  • extending the specifications as to what needs to be added by other contributors
  • ensuring that all the Latex code up to this point is free of mistakes that prevent compilation

• Exerciser: thinks of exercises and adds them to the lecture notes; ideally, this student will handle all the typesetting associated with exercises, but they may ask the artist for help with figures

• Solver: writes up the solutions to all exercises; again, this student should handle all of the typesetting related to solutions on their own, though they may ask the artist for help with figures

• Artist: creates figures and trees as directed by hammer and sandpaper, but may also help the exerciser and solver; trees should be typeset with forest, figures with tikz; it is important to write clean, reusable tikz code (styles, relative node placement, foreach loops)

• Editor: reads the draft version produced from by team members with one of the previous 5 roles and revises it with an eye towards clarity and style

• Reader: reads the draft version, points out if some passages are unclear, and relays that information to the editor with suggestions for improvements

• Master: manages the playground repository; this means distributing files as necessary, merging in changes, ensuring that team members follow the repository policies, and helping out with git-related problems

• Whip: manages the workflow of the entire team; this includes

  • working out task interdependencies (e.g. a figure cannot be completed until the example has been fully specified),
  • setting deadlines for certain tasks based on these interdependencies
  • distributing the workload between team members
  • aiding communication between team members
  • anything else that is needed to keep the group working like a well-oiled machine

Role Assignments

Role	Student
Whip	Hwichan
Master	Aniello
Editor	Jon
Reader	Sophie
Hammer	Jimmy, So Young
Sandpaper	Jimmy, So Young
Artist	Alëna
Exerciser	Logan
Solver	Hongchen, Lei

Essential Git Commands

• Clone playground repository

  git clone https://github.com/CompLab-StonyBrook/mgproc.git

• Get most recent version of branch

  git pull origin <branch>

• Create new branch :

  git branch <feature>

• Show current branch (marked by asterisk):

  git branch

• Switch to branch :

  git checkout <feature>

• Update current branch to the most recent commit in :

  git merge <branch>

  This is useful to bring in new files.

• As before, but if there is a merge conflict, prefer our version:

  git merge -s recursive -X ours <branch>

  With proper workflow procedure, this makes it easy to bring in new files from raw.

• As before, but if there is a merge conflict, prefer the version from the other branch:

  git merge -s recursive -X theirs <branch>

  Useful if a unit has been completed and you want to update all files to the revised version in master.

• Stage specific files , , ..., that have been changed:

  git add <file1> <file2> ... <filen>

• Stage all changed files:

  git add .

• Check status of local repository:

  git status

• Commit staged files:

  git commit

• Pushing your changes to remote branch :

  git push origin <feature>

Link List

Using git

• Github app for Windows; supports only Windows 7 or later
• Github app for Mac; supports only OS X 10.9 or later
• List of alternative GUI clients for git
• Tutorials for using git via the command line
• Official documentation for git

Markdown

• Interactive tutorial to markdown basics
• Complete markdown syntax
• Overview of Github's markdown dialect

LaTeX

• Overleaf (formerly writeLaTeX) is an online LaTeX editor with live preview
• List of commonly used math symbols
• Andrew Roberts' Getting to Grips with LaTeX

Python

• A succinct yet extensive tutorial for Python 3
• The official Python 3 documentation
• Automate the Boring Stuff with Python is an excellent introduction that covers the basics of Python and applies them to real-world tasks.