|
| 1 | +--- |
| 2 | +title: "Lab 0: Getting Started" |
| 3 | +--- |
1 | 4 |
|
2 | | -# Lab 0: Getting Started |
3 | | - |
4 | | -The goals for this tutorial are: |
5 | | -* to set up installations for your local development environment |
6 | | -* to learn how to serve your pages so that you can see/interact with them while you are coding |
7 | | -* to get comfortable with the Github workflow |
8 | | -* to set up a public site to showcase your work |
9 | | - |
10 | | -The assignment requirements are as follows: |
11 | | -1. Replicate the local environment created in class on your own computer ([Installations](#installations)) |
12 | | -2. Fork this repository, set up github pages, and initialize your upstream repository ([Github Setup](#github-setup)) |
13 | | -3. Submit your [deployed link](#4-set-up-your-github-pages-for-your-deployment) as a comment on the lab 0 commons post. |
14 | | - |
15 | | -# Installations |
16 | | - |
17 | | -The first step is to install all the appropriate software to get our environment together. Please install the following on the computer you intend to complete all the tutorials from. |
18 | | - |
19 | | -*Note*: while VS code is an application, the other softwares are installed via your terminal or bash. If this is your first time working with your terminal, check out [working with your terminal](#working-with-your-terminal). |
20 | | - |
21 | | -- [VS Code](https://code.visualstudio.com/) - free code editor and IDE (our recommendation). This is an application to view files and code. This application also includes many handy extensions that can help us with [version control](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support) and [file serving](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer). |
22 | | - - You may also use another code editor that has AI integration, like [cursor](https://cursor.com/), but these ai integrations typically require payment after reacting an interaction limit. |
23 | | -- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) version control software. You will also need an account on [Github.com](https://github.com/). |
24 | | - - if you have a mac, and you have installed Xcode, you _already have git_. You can test this by opening your terminal and running `git --version`. |
25 | | - - if you are using a PC, an application called "git bash" will be part of the default git install. You may prefere to use this application rather than the "command prompt" for git commands. |
26 | | - - all installation details are included in the [Getting Started Installing Git link](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). |
27 | | - - an alternative for both mac and pc is to use the [source control](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support) options that come with the default VS Code installation. This is often easier than opening terminal each time and offers many of the same actions. |
28 | | -- [Node](https://nodejs.org/en/download/) - javascript development software. You can check if the install was succesful by running `node -v` in your command line or terminal. It should return your version number. |
29 | | - |
30 | | -# Github Setup |
31 | | - |
32 | | -You can read more about `forking`, `syncing`, and the overall github flow [here](https://help.github.com/en/github/getting-started-with-github/fork-a-repo). |
33 | | - |
34 | | -## 1. On Gitub, within to our [main repository](https://github.com/InteractiveDataVis/Interactive-Data-Vis-Fall2025.git) and [`fork`](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) this repository into your own account. |
35 | | - |
36 | | -To do this, click on the "fork" button on the top right of this github account. |
37 | | - |
38 | | -<img src='assets/fork.png' width='700px'> |
39 | | - |
40 | | -This creates a clone of our class repository in your own github account. After the fork, you can see this worked by confirming your github username appears before the repository name: |
41 | | - |
42 | | -<img src='assets/forked.png' width='700px'> |
43 | | - |
44 | | -This repository is _your_ personal copy of the existing repository. This will be where you do all your lab work, and will include the deployed links that you will submit when turning in your assignments. |
45 | | - |
46 | | -## 2. On GitHub, navigate to **your fork** of the repository and clone it to your local computer. |
47 | | - |
48 | | -To do this, navigate to the folder where you want to save your files (I like to save mine in `Documents/Repositories`). (Hint: `cd` or 'change directory' will help you get there through terminal). |
49 | | - |
50 | | -```sh |
51 | | -# from Terminal: |
52 | | - |
53 | | -# navigate to where you want to save your code |
54 | | -$ cd PATH_TO_YOUR/FOLDER |
55 | | - |
56 | | -# clone your fork to your local computer |
57 | | -$ git clone https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025 |
58 | | - |
59 | | -# `cd` (change directory) into this repository |
60 | | -$ cd Interactive-Data-Vis-Fall2025 |
61 | | -``` |
62 | | - |
63 | | -## 3. Set up your local repository so that it links back to the course repository. |
64 | | - |
65 | | -We do this so that you can keep your local branch synced up with the main course repository when we update the material. With this set up, you can simply `pull` in the new changes from our original class repository. |
66 | | - |
67 | | -```sh |
68 | | -#See current remote branches: |
69 | | - |
70 | | -$ git remote -v |
71 | | -> origin https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025 (fetch) |
72 | | -> origin https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025 (push) |
73 | | - |
74 | | -# notice currently this is only tracking your version of the repository. |
75 | | -``` |
76 | | - |
77 | | -Add an `upstream` remote branch so you can keep yours synced with the main class repository: |
78 | | - |
79 | | -```sh |
80 | | -$ git remote add upstream https://github.com/InteractiveDataVis/Interactive-Data-Vis-Fall2025.git |
81 | | -``` |
82 | | - |
83 | | -Check remote branches again to ensure that the update worked. You should see 2 sets of branches, `origin` which links back to your fork, and `upstream` which references back to the course repository: |
84 | | - |
85 | | -```sh |
86 | | -$ git remote -v |
87 | | -> origin https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025 (fetch) |
88 | | -> origin https://github.com/[YOUR_USERNAME]/Interactive-Data-Vis-Fall2025 (push) |
89 | | -> upstream https://github.com/InteractiveDataVis/Interactive-Data-Vis-Fall2025.git (fetch) |
90 | | -> upstream https://github.com/InteractiveDataVis/Interactive-Data-Vis-Fall2025.git (push) |
91 | | - |
92 | | -# now notice see that we are tracking both the original and your version of the repository |
93 | | -``` |
94 | | - |
95 | | - |
96 | | -## 4. Set up your Github Pages for your deployment |
97 | | - |
98 | | -We use [Github Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/what-is-github-pages) to serve our websites publicly. Github Pages is static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website. |
99 | | - |
100 | | -To [set up your github pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site), you can go to your repository's `Settings` tab and then scroll down to `Pages` section. Select `Github Actions` as source ("Deploy from a branch"). |
101 | | - |
102 | | -<img src='assets/pages.png' width='700px'> |
103 | | - |
104 | | -The workflow code is already included in the main class repository. When you push your changes up to github, then your site will automatically be redeployed and be avallable at `https://[YOUR_USERNAME].github.io/[YOUR_REPOSITORY_NAME]/`. |
105 | | - |
106 | | -You can see all the deployments triggered from pushed in the deployments section of your repository page. |
107 | | - |
108 | | -<img src='assets/deployments.png' width='700px'> |
109 | | - |
110 | | -*NOTE*: You must navidate in the URL to a folder with an index.html, or else you will get a 404. This will take a few minutes to update with any pushed changes. |
111 | | - |
112 | | -### 5. Push up and deploy your changes |
113 | | - |
114 | | -[Note: VS Code has some great [tools](https://code.visualstudio.com/docs/editor/versioncontrol#_git-support) built in to help with this process.] |
115 | | - |
116 | | -When you have made a change that you want to keep, you can commit your changes: |
117 | | - |
118 | | -```sh |
119 | | -# see which files have changes associated with them |
120 | | -git status |
121 | | - |
122 | | -# add, or 'stage', files or folders for this commit |
123 | | -git add [path/fileName] |
124 | | - |
125 | | -# commit the files with a brief explanation of what you are changing |
126 | | -# ex: `git commit -m 'add bar chart legend` |
127 | | -git commit -m 'message regaring what changes you are commiting' |
128 | | -``` |
129 | | - |
130 | | -When you are ready to push up your code to your remote repository, you can run: |
131 | | - |
132 | | -```sh |
133 | | -$ git push |
134 | | -``` |
135 | | - |
136 | | -**That's it! Now you are ready to create, update, and deploy your own websites 🎉!** |
137 | | - |
138 | | -# Appendix |
139 | | - |
140 | | -### Working with your terminal |
141 | | - |
142 | | -Your computer, mac or pc, includes a command line interface that lets you communicate with your operating system. For macs, that app is called "terminal", and on windows machines, its the "command prompt". |
143 | | - |
144 | | - |
145 | | - |
146 | | - |
147 | | - |
148 | | -More resources to understand these interfaces: |
149 | | -* Mac: [What is terminal on mac?](https://support.apple.com/guide/terminal/what-is-terminal-trmld4c92d55/mac) |
150 | | -* PC: [cmd.exe Wiki](https://en.wikipedia.org/wiki/Cmd.exe) |
151 | | -* PC: [Command Prompt Basics (youtube tutorial)](https://www.youtube.com/watch?v=QBWX_4ho8D4) |
152 | | -* [Complete List: Command Line Prompt (CMD)](https://www.codecademy.com/article/command-line-commands) |
153 | | - |
154 | | - |
155 | | -### Keeping your repository synced |
156 | | - |
157 | | -As the semester progresses, updates may be pushed to the class repository. The following terminal commands can keep your repo [synced](https://help.github.com/en/github/getting-started-with-github/fork-a-repo#keep-your-fork-synced). Make sure to do this before working on new code to ensure that you are working off of the latest updates. |
158 | | - |
159 | | -```sh |
160 | | -# pulls the upstream changes and stores them in `upstream/main` |
161 | | -$ git fetch upstream |
162 | | -``` |
163 | | - |
164 | | -```sh |
165 | | -# merges the changes from upstream into your current branch |
166 | | -$ git merge upstream/main |
167 | | -``` |
168 | | - |
169 | | -(You can read more information about this process [here](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)) |
170 | | - |
171 | | -### Helpful terminal commands for navigation |
172 | | - |
173 | | -**Windows Command Prompt (CMD)** |
174 | | - |
175 | | -- `dir`: List files and folders in current directory |
176 | | -- `cd [folder]`: Change directory (e.g., cd Documents) |
177 | | -- `cd ..`: Go up one directory level |
178 | | -- `cd \`: Go to root directory |
179 | | -- `mkdir [name]`: Create new folder |
180 | | -- `rmdir [name]`: Remove empty folder |
181 | | -- `del [filename]`: Delete file |
182 | | -- `copy [source] [destination]`: Copy files |
183 | | -- `move [source] [destination]`: Move/rename files |
184 | | - |
185 | | -**macOS/Linux Terminal** |
186 | | - |
187 | | -- `ls`: List files and folders (ls -la for detailed view) |
188 | | -- `cd [folder]`: Change directory |
189 | | -- `cd ..`: Go up one directory |
190 | | -- `cd ~`: Go to home directory |
191 | | -- `pwd`: Show current directory path |
192 | | -- `mkdir [name]`: Create folder |
193 | | -- `rmdir [name]`: Remove empty folder |
194 | | -- `rm [filename]`: Delete file (rm -r [folder] for folders) |
195 | | -- `cp [source] [destination]`: Copy files |
196 | | -- `mv [source] [destination]`: Move/rename files |
197 | | - |
| 5 | +Lab instructions in the [readme.md](./README.md). |
0 commit comments