update git docs/philosophy/readme

README.md

@@ -3,9 +3,21 @@
 
 ![Ubuntu Build Status](https://github.com/CMU-Graphics/Scotty3D/workflows/Ubuntu/badge.svg) ![MacOS Build Status](https://github.com/CMU-Graphics/Scotty3D/workflows/MacOS/badge.svg) ![Windows Build Status](https://github.com/CMU-Graphics/Scotty3D/workflows/Windows/badge.svg)
 
-Welcome to Scotty3D! This 3D graphics software implements interactive mesh
-editing, realistic path tracing, and dynamic animation. Implementing the
-functionality of the program constitutes the majority of the coursework for
-15-462/662 Computer Graphics at Carnegie Mellon University
+Welcome to Scotty3D! This 3D graphics software package includes components for interactive mesh
+editing, realistic path tracing, and dynamic animation. Implementing functionality in each of these areas
+constitutes the majority of the coursework for 15-462/662 (Computer Graphics) at Carnegie Mellon University
 
 Please visit the [documentation website](https://cmu-graphics.github.io/Scotty3D/).
+
+## Sampled Screenshots (Fall 2020)
+
+### MeshEdit
+
+![fall 2020 meshes](docs/results/me_f20.png)
+
+### PathTracer
+
+![fall 2020 path tracer 0](docs/results/pt_f20_0.png)
+![fall 2020 path tracer 1](docs/results/pt_f20_1.png)
+![fall 2020 path tracer 2](docs/results/pt_f20_2.png)
+![fall 2020 path tracer 3](docs/results/pt_f20_3.png)

docs/building.md

@@ -6,11 +6,11 @@ permalink: /build/
 
 # Building Scotty3D
 
-To get the code:
+![Ubuntu Build Status](https://github.com/CMU-Graphics/Scotty3D/workflows/Ubuntu/badge.svg) ![MacOS Build Status](https://github.com/CMU-Graphics/Scotty3D/workflows/MacOS/badge.svg) ![Windows Build Status](https://github.com/CMU-Graphics/Scotty3D/workflows/Windows/badge.svg)
 
-```git clone https://github.com/CMU-Graphics/Scotty3D.git```
+To get a copy of the codebase, see [Git Setup](git).
 
-Note: the first build on any platform will be very slow, as it must compile the source-based dependencies. Subsequent builds will only need to re-compile your edited Scotty3D code.
+Note: the first build on any platform will be very slow, as it must compile most dependencies. Subsequent builds will only need to re-compile your edited Scotty3D code.
 
 ### Linux 
 

docs/git.md

+---
+layout: default
+title: "GitHub Setup"
+permalink: /git/
+---
+
+Please do not use a public github fork of this repository! We do not want solutions to be public. You should work in your own private repo.
+We recommended creating a mirrored private repository with multiple remotes. The following steps go over how to achieve this.
+
+The easiest (but not recommended) way is to download a zip from GitHub and make a private repository from that. The main disadvantage with this is that whenever there is an update to the base code, you will have to re-download the zip and manually merge the differences into your code. This is a pain, and you already have a lot to do in 15462/662, so instead, let `git` take care of this cumbersome "merging-updates" task:
+
+1. Clone Scotty3D normally
+    - `git clone https://github.com/CMU-Graphics/Scotty3D.git`
+
+2. Create a new private repository (e.g. `MyScotty3D`)
+    - Do not initialize this repository - keep it completely empty.
+    - Let's say your repository is now hosted here: `https://github.com/your_id/MyScotty3D.git`
+
+3. Ensure that you understand the concept of `remote`s in git.
+    - When you clone a git repository, the default remote is named 'origin' and set to the URL you cloned from.
+    - We will set the `origin` of our local clone to point to `MyScotty3D.git`, but also have a remote called `sourcerepo` for the public `Scotty3D` repository.
+
+4. Now go back to your clone of Scotty3D. This is how we add the private remote: 
+    - Since we cloned from the `CMU-Graphics/Scotty3D.git` repository, the current value of `origin` should be `https://github.com/CMU-Graphics/Scotty3D.git`
+        - You can check this using `git remote -v`, which should show:
+            ```
+            origin      https://github.com/CMU-Graphics/Scotty3D.git (fetch)
+            origin      https://github.com/CMU-Graphics/Scotty3D.git (push)
+            ```
+    - Rename `origin` to `sourcerepo`:
+        - `git remote rename origin sourcerepo`
+    - Add a new remote called `origin`:
+        - `git remote add origin https://github.com/your_id/MyScotty3D.git`
+    - We can now push the starter code to our private copy:
+        - `git push origin -u master`
+
+5. Congratulations! you have successfully _mirrored_ a git repository with all past commits intact. Let's see a case where this becomes very useful: we start doing an assignment and commit regularly to our private repo (our `origin`). Then the 15-462 staff push some new changes to the Scotty3D skeleton code. We now want to pull the changes from our `sourcerepo`. But, we don't want to mess up the changes we've added to our private copy. Here's where git comes to the rescue:
+    - First commit all current changes to your `origin`
+    - Run `git pull sourcerepo master` - this pulls all the changes from `sourcerepo` into your local folder
+    - If there are files that differ in your `origin` and in the `sourcerepo`, git will attempt to automatically merge the changes. Git may create a "merge" commit for this. 
+    - Unfortunately, there may be merge conflicts. Git will handle as many merges as it can, and then will then tell you which files have conflicts that need manual resolution. You can resolve those conflicts in your text editor and create a new commit to complete the `merge` process.
+    - After you have completed the merge, you now have all the updates locally. Push to your private origin to include the changes there too:
+        - `git push origin master`
+

docs/index.md

 
 # Scotty3D
 
-Welcome to Scotty3D! This 3D graphics software implements interactive mesh
-editing, realistic path tracing, and dynamic animation. Implementing the
-functionality of the program constitutes the majority of the coursework for
-15-462/662 Computer Graphics at Carnegie Mellon University
+Welcome to Scotty3D! This 3D graphics software package includes components for interactive mesh
+editing, realistic path tracing, and dynamic animation. Implementing functionality in each of these areas
+constitutes the majority of the coursework for 15-462/662 (Computer Graphics) at Carnegie Mellon University
 
-The [building Scotty3D](build) page describes how to build and run `Scotty3D` on various platforms.
+These pages describe how to set up and use Scotty3D. Start here!
+- [Git Setup](git): create a private git mirror that can pull changes from Scotty3D. 
+- [Building Scotty3D](build): build and run Scotty3D on various platforms.
+- [User Guide](guide): learn the intended functionality for end users.
 
-The [User Guide](guide) describes the intended functionality of the software to an end user.
-
-The components of the Developer Manual (your assignments) are organized under the three main components of the software:
+The developer manual describes what you must implement to complete Scotty3D. It is organized under the three main components of the software:
 - [MeshEdit](meshedit)
 - [PathTracer](pathtracer)
 - [Animation](animation)
 
-Finally, please read through the [Project Philosophy](philosophy) before you begin work.
+## Project Philosophy
+
+Welcome to your first day of work at Scotty Industries! Over the next few months
+you will implement core features in Scotty Industries' flagship product
+Scotty3D, which is a modern package for 3D modeling, rendering, and animation.
+In terms of basic structure, this package doesn't look much different from
+"real" 3D tools like Maya, Blender, modo, or Houdini. Your overarching goal is
+to use the developer manual to implement a package that
+works as described in the [User Guide](guide), much as you would at a real
+software company (more details below).
+
+Note that the User Guide is **not** an Assignment Writeup. The User Guide
+contains only instructions on how to use the software, and serves as a
+high-level specification of _what the software should do_. The Developer Guide
+contains information about the internals of the code, i.e., _how the software
+works_. This division is quite common in software development: there is a
+**design specification** or "design spec", and an **implementation** that
+implements that spec. Also, as in the real world, the design spec does _not_
+necessarily specify every tiny detail of how the software should behave! Some
+behaviors may be undefined, and some of these details are left up to the party
+who implements the specification. A good example you have already seen is
+OpenGL, which defines some important rules about how rasterization should
+behave, but is not a "pixel-exact" specification. In other words, two different
+OpenGL implementations from two different vendors (Intel and NVIDIA, say) may
+produce images that differ by a number of pixels. Likewise, in this assignment,
+your implementation may differ from the implementation of your classmates in
+terms of the exact values it produces, or the particular collection of
+corner-cases it handles. However, as a developer you should strive to provide a
+solution that meets a few fundamental criteria:
+
+*   [Failing gracefully](https://en.wikipedia.org/wiki/Fault_tolerance) is
+preferable to failing utterly---for instance, if a rare corner case is difficult
+to handle, it is far better to simply refuse to perform the operation than to
+let the program crash! 
+*   Your implementation should follow the [principle of least
+surprise](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). A user
+should be able to expect that things behave more or less as they are described
+in the User Guide. 
+*   You should not use an algorithm whose performance is [asymptotically
+worse](https://en.wikipedia.org/wiki/Asymptotic_computational_complexity) just
+because it makes your code easier to write (for instance, using [bubble
+sort](https://en.wikipedia.org/wiki/Bubble_sort) rather than [merge
+sort](https://en.wikipedia.org/wiki/Merge_sort) on large data sets). 
+*   That being said, when it comes to performance, [premature optimization is
+the root of all evil!](https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize) The only way to know whether an optimization matters is to [measure performance](https://en.wikipedia.org/wiki/Profiling_(computer_programming)), and understand [bottlenecks](https://en.wikipedia.org/wiki/Program_optimization#Bottlenecks). 
+*   Finally, you should take pride in your craft. Beautiful things just tend to work better.
+
+Just to reiterate the main point above:
+
+**As in real-world software development, we will not specify every little detail
+about how methods in this assignment should work!**
+
+If you encounter a tough corner case (e.g., "how should edge flip behave for a
+tetrahedron"), we want you to _think about what a good **design choice** might
+be_, and implement it to the best of your ability. This activity is part of
+becoming a world-class developer. However, we are more than happy to discuss
+good design choices with you, and you should also feel free to discuss these
+choices with your classmates. Practically speaking, it is ok for routines to
+simply show an error if they encounter a rare and difficult corner case---as long as it
+does not interfere with successful operation of the program (i.e., if it does
+not crash or yield bizarre behavior). Your main goal here above all else should be 
+to develop _effective tool for modeling, rendering, and animation_.

docs/philosophy.md

----
-layout: default
-title: "Project Philosophy"
-permalink: /philosophy/
----
-
-# Project Philosophy
-
-Welcome to your first day of work at Scotty Industries! Over the next few months
-you will implement core features in Scotty Industries' flagship product
-Scotty3D, which is a modern package for 3D modeling, rendering, and animation.
-In terms of basic structure, this package doesn't look much different from
-"real" 3D tools like Maya, Blender, modo, or Houdini. Your overarching goal is
-to use the developer manual to implement a package that
-works as described in the [User Guide](guide/guide.md), much as you would at a real
-software company (more details below).
-
-Note that the User Guide is **not** an Assignment Writeup. The User Guide
-contains only instructions on how to use the software, and serves as a
-high-level specification of _what the software should do_. The Developer Guide
-contains information about the internals of the code, i.e., _how the software
-works_. This division is quite common in software development: there is a
-**design specification** or "design spec", and an **implementation** that
-implements that spec. Also, as in the real world, the design spec does _not_
-necessarily specify every tiny detail of how the software should behave! Some
-behaviors may be undefined, and some of these details are left up to the party
-who implements the specification. A good example you have already seen is
-OpenGL, which defines some important rules about how rasterization should
-behave, but is not a "pixel-exact" specification. In other words, two different
-OpenGL implementations from two different vendors (Intel and NVIDIA, say) may
-produce images that differ by a number of pixels. Likewise, in this assignment,
-your implementation may differ from the implementation of your classmates in
-terms of the exact values it produces, or the particular collection of
-corner-cases it handles. However, as a developer you should strive to provide a
-solution that meets a few fundamental criteria:
-
-*   [Failing gracefully](https://en.wikipedia.org/wiki/Fault_tolerance) is
-preferable to failing utterly---for instance, if a rare corner case is difficult
-to handle, it is far better to simply refuse to perform the operation than to
-let the program crash! 
-*   Your implementation should follow the [principle of least
-surprise](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). A user
-should be able to expect that things behave more or less as they are described
-in the User Guide. 
-*   You should not use an algorithm whose performance is [asymptotically
-worse](https://en.wikipedia.org/wiki/Asymptotic_computational_complexity) just
-because it makes your code easier to write (for instance, using [bubble
-sort](https://en.wikipedia.org/wiki/Bubble_sort) rather than [merge
-sort](https://en.wikipedia.org/wiki/Merge_sort) on large data sets). 
-*   That being said, when it comes to performance, [premature optimization is
-the root of all evil!](https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize) The only way to know whether an optimization matters is to [measure performance](https://en.wikipedia.org/wiki/Profiling_(computer_programming)), and understand [bottlenecks](https://en.wikipedia.org/wiki/Program_optimization#Bottlenecks). 
-*   Finally, you should take pride in your craft. Beautiful things just tend to work better.
-
-Just to reiterate the main point above:
-
-**As in real-world software development, we will not specify every little detail
-about how methods in this assignment should work!**
-
-If you encounter a tough corner case (e.g., "how should edge flip behave for a
-tetrahedron"), we want you to _think about what a good **design choice** might
-be_, and implement it to the best of your ability. This activity is part of
-becoming a world-class developer. However, we are more than happy to discuss
-good design choices with you, and you should also feel free to discuss these
-choices with your classmates. Practically speaking, it is ok for routines to
-simply show an error if they encounter a rare and difficult corner case---as long as it
-does not interfere with successful operation of the program (i.e., if it does
-not crash or yield bizarre behavior). Your main goal here above all else should be 
-to develop _effective tool for modeling, rendering, and animation_.