How to Contribute to Theory Group Website

0.1 Have git installed on your laptop

First of all, you need to have git installed on your local computer.

Note that git and GitHub are two different things. git is a software that runs locally on your computer to help you organize your file changes. GitHub is an online platform that allows people to upload their code to the Internet and collaborate with other people.

If you use MacOS, then git is already pre-installed for you. If you are using Windows or Linux or other OS, then follow this link to install: https://github.com/git-guides/install-git

0.2 Create a GitHub account

Secondly, you need to register a GitHub account: https://github.com/.

If you do not have a GitHub account, I personally suggest that you use your personal email (e.g. gmail) to register for GitHub as you will lose your school email once you graduate.

0.3 Install GitHub CLI

CLI means Command Line Interface.

Third, you need to install GitHub CLI: https://cli.github.com/manual/installation. We choose to use GitHub CLI to submit pull requests because you can then do all the commands from your terminal, which is convenient. There are other ways to submit pull requests. If you are a seasoned GitHub user, feel free to use anything you like and you do not have to follow this guide.

To install, if you are using MacOS and have homebrew installed, you can run the following command:

	brew install gh

Once you have GitHub CLI installed, first login to GitHub on your browser, then go back to your terminal and authenticate your GitHub CLI with your GitHub account by using the following command:

	gh auth login

Follow the instructions and you should see similar outputs as follows:

	->  ~ gh auth login
	? What account do you want to log into? GitHub.com
	? What is your preferred protocol for Git operations? HTTPS
	? Authenticate Git with your GitHub credentials? Yes
	? How would you like to authenticate GitHub CLI? Login with a web browser

	! First copy your one-time code: 4586-56B3
	Press Enter to open github.com in your browser...
	[check] Authentication complete.
	- gh config set -h github.com git_protocol https
	[check] Configured git protocol
	[check] Logged in as ziyang-theory
	->  ~

Step 1: Clone the Repo to Your Local Computer

1.1 First Time

The first time you need to create a local workspace. Open your command line terminal on your computer.

First, create a directory/folder in some place of your choice. For example, since I use Mac OS, I will just create a new directory in my Desktop

	cd ~/Desktop/
	mkdir uoft_theory_website
	cd uoft_theory_website

You do not have to use uoft_theory_website as the name, you can use any name you like. Then you can clone the GitHub repo under the current directory using the following command

	git clone https://github.com/utoronto-theory/webpage.git

and you should see the following console output

	Cloning into 'webpage'...
	remote: Enumerating objects: 199, done.
	remote: Counting objects: 100% (34/34), done.
	remote: Compressing objects: 100% (24/24), done.
	remote: Total 199 (delta 18), reused 24 (delta 10), pack-reused 165
	Receiving objects: 100% (199/199), 6.44 MiB | 6.04 MiB/s, done.
	Resolving deltas: 100% (62/62), done.

Now if you type ls, you should be able to see a directory called webpage. Now the repository has already been cloned to your local computer. In the end

	cd webpage

You are now in your local copy of the GitHub repository.

1.2 After the First Time

You need to first go to your own copy of the repo on your GitHub account: https://github.com/ziyang-theory/webpage (replace "ziyang-theory" with your GitHub own account id). Click the [Sync fork] button to first sync your online clone with the original repository.

Secondly, open a terminal on your laptop, and go to the webpage directory, and type

	git pull --rebase

By doing this, you will sync up your local workspace to make it up-to-date. If you do not do this, there might be a merge conflict if someone else is also contributing to the website so you are not working based on the most up-to-date code. Now, you can go ahead and make code changes.

Step 2: Make Code Changes

2.1 Open the local copy of the website from your browser

Open any browser of your choice (Firefox, Chrome, etc.), and open the index.html file under your repository .../Desktop/uoft_theory_website/webpage/index.html

In Mac OS, you can press (Command + O) to open a new file, and then select the index.html file. The file path is (~/Desktop/ufot_theory_website/webpage/index.html), then you are able to open the theory group's webpage locally on your computer.

Keep this browser tab open, and whenever you make a code change, you can refresh (Command + R) the browser and examine your changes visually.

2.2 Change the source code

Now open any text editor/IDE of your choice. For example, I use Sublime Text. Then open the source code file you want to change.

For example, I would like to link my personal website to my name, so I open students.html file, and make some simple html changes.

We believe everyone who wants to make changes knows some basic html stuff. If you are unsure, just Google "how to do XXX html", and the first option would usually be W3Schools, which gives a detailed explanation on html and css stuff.

After you make the code changes, press (Command + S) to save the file, and then switch to brower and refresh the browser to see if you like the updated changes. If you are satisfied with your changes, you can type the following command on the terminal:

	git status

You should see the students.html now turns red. That means the file has been changed. Then type:

	git add .

After this, the students.html should turn green, which means the changes have been added to git's version control log. Lastly, in order to finalize the change in git and give descriptions, type:

	git commit

After you type git commit command, by default a vim text editor will show up on your console, here you need to write the title of your commit and describing your change using simple present tense. For example, here is what I typed for my commit:

Update students page with links to personal websites

This commit updates the students page on the theory group website. It adds 
links to each student's personal websites, if available. It also fixes the
ordering of students names to follow alphabetical order by last name. It 
also changes students' names to their preferred names, which is usually the
name they use when publishing papers.

Then press esc and then type in :wq to save and quit the vim editor. Now you are ready to submit a pull request.

Step 3: Submit a Pull Request

The pull request is for you to submit your local code changes from your computer to the GitHub repository.

Before submitting a pull request, make sure you have already finished the pre-requisite and already logged in from the GitHub CLI.

Now all you need to do is to create a pull request

	gh pr create

and then follow the instructions to submit the pull request (You need to write the title but you can skip the body)

->  webpage git:(main) gh pr create
	->  webpage git:(main) gh pr create
	? Where should we push the 'main' branch? Create a fork of utoronto-theory/webpage

	Creating pull request for ziyang-theory:main into main in utoronto-theory/webpage

	? Title Update students page with links to personal websites
	? Body 
	? What's next? Submit
	remote: Repository not found.
	fatal: repository 'https://github.com/ziyang-theory/webpage.git/' not found
	waiting 2 seconds before retrying...
	remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
	To https://github.com/ziyang-theory/webpage.git
   		d696d2a..eb5f629  HEAD -> main
	branch 'main' set up to track 'fork/main'.
	https://github.com/utoronto-theory/webpage/pull/1
	->  webpage git:(main)

Note that if it is your first time running the command, it will also create a copy of the original GitHub repository to your online GitHub account's repository (e.g. https://github.com/ziyang-theory/webpage/tree/main).

Now the pull request has been successfully submitted, you can go to GitHub https://github.com/utoronto-theory/webpage/pulls and check your pull request's status. The reviwer will receive a notification and review your changes.

In order to help the reviewer understand the change, you might want to take a screenshot of your browser to show what your change looks like, and paste the screenshots in the comment section of your pull request on GitHub. See this pull request as an example.

Once your pull request has been approved, the theory group's website will be automatically updated within 24 hours to reflect your change.